Settings & Profiles

PrivateGPT is configured through YAML settings files. The base file is settings.yaml at the project root. Additional profiles can be layered on top to override or extend the base config.

Profiles

A profile is a file named settings-{name}.yaml. Activate one or more profiles at startup by setting PGPT_PROFILES:

$
PGPT_PROFILES=model private-gpt serve

Multiple profiles are merged in order — later profiles override earlier ones:

$
PGPT_PROFILES=model,local private-gpt serve

This loads settings.yaml, then merges settings-model.yaml, then settings-local.yaml on top.

The typical use case is a settings-model.yaml generated by make auto-discover-models that defines your LLM and embedding models without modifying the base config.

Environment variable expansion

Any value in a settings file can reference an environment variable:

1
server:
2
  port: ${PORT:8080}

The syntax is ${VARIABLE_NAME:default_value}. If the variable is not set, the default is used. Variables with no default will raise an error at startup if unset.

Settings folder

By default, PrivateGPT looks for settings files in the project root. Override this with:

$
PGPT_SETTINGS_FOLDER=/path/to/settings private-gpt serve

Data settings

PGPT_ENABLE_VISION_FALLBACK

Controls whether PDF ingestion retries extraction with the vision reader (VLM-based) when the primary reader (e.g. Docling) fails to extract meaningful text — typically due to unmapped glyphs from CID fonts without a ToUnicode map.

1
data:
2
  enable_vision_fallback: ${PGPT_ENABLE_VISION_FALLBACK:false}

Requires at least one multimodal model configured. See Model Configuration for setup instructions.