> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.privategpt.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.privategpt.dev/_mcp/server.

# Settings & Profiles

> Settings files, profiles, and environment variable expansion.

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`:

```bash
PGPT_PROFILES=model private-gpt serve
```

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

```bash
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:

```yaml
server:
  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:

```bash
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.

```yaml
data:
  enable_vision_fallback: ${PGPT_ENABLE_VISION_FALLBACK:false}
```

Requires at least one multimodal model configured. See [Model Configuration](/configuration/advanced) for setup instructions.