# How to Customize the DeepWiki Configuration Directory Using the DEEPWIKI_CONFIG_DIR Environment Variable

> Learn how to customize the DeepWiki configuration directory using the DEEPWIKI_CONFIG_DIR environment variable. Easily load custom settings for your DeepWiki project.

- Repository: [ASYNCFUNC/deepwiki-open](https://github.com/asyncfuncai/deepwiki-open)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Set the `DEEPWIKI_CONFIG_DIR` environment variable to an absolute path containing your JSON configuration files, and DeepWiki will load settings from that directory instead of the default `api/config/` folder.**

DeepWiki is an open-source documentation generator that loads runtime settings from JSON configuration files. By default, these files reside in the `api/config/` directory bundled with the source code. For production deployments or environment-specific customization, you can customize the DeepWiki configuration directory using the `DEEPWIKI_CONFIG_DIR` environment variable to point to an external folder.

## How DEEPWIKI_CONFIG_DIR Works Internally

DeepWiki’s configuration system relies on a runtime check that prioritizes the environment variable over the bundled defaults.

### Configuration Loading in api/config.py

At import time, the module [`api/config.py`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/api/config.py) reads the environment variable on line 55:

```python

# api/config.py

CONFIG_DIR = os.environ.get('DEEPWIKI_CONFIG_DIR', None)

```

If `DEEPWIKI_CONFIG_DIR` is not set, `CONFIG_DIR` remains `None`, triggering the fallback behavior.

### Path Resolution in load_json_config()

The function `load_json_config()` (lines 103–108) handles the actual file path resolution:

```python
def load_json_config(filename):
    # ...

    if CONFIG_DIR:
        config_path = Path(CONFIG_DIR) / filename
    else:
        config_path = Path(__file__).parent / "config" / filename
    # ...

```

When `CONFIG_DIR` is defined, DeepWiki constructs the path using `Path(CONFIG_DIR) / filename`, reading directly from your custom location. Otherwise, it defaults to `api/config/` relative to the module’s location.

## Setting DEEPWIKI_CONFIG_DIR in Different Environments

You can export the variable using shell commands, Docker configurations, or programmatically within Python.

### Shell Environment (Linux/macOS)

For a one-off execution or temporary session:

```bash
export DEEPWIKI_CONFIG_DIR=/opt/deepwiki/custom-config
deepwiki  # or python -m api.main

```

To persist the setting, add the `export` line to your shell profile (e.g., `~/.bashrc` or `~/.zshrc`).

### Docker and Docker Compose

Mount your custom configuration as a volume and set the environment variable in your [`docker-compose.yml`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/docker-compose.yml):

```yaml
services:
  deepwiki:
    image: asyncfuncai/deepwiki-open:latest
    environment:
      - DEEPWIKI_CONFIG_DIR=/app/config
    volumes:
      - ./my-config:/app/config:ro

```

This approach keeps sensitive or environment-specific settings outside the container image.

### Programmatic Configuration (Python)

When embedding DeepWiki within another application or testing environment, set the variable before importing DeepWiki modules:

```python
import os
os.environ["DEEPWIKI_CONFIG_DIR"] = "/home/user/my-deepwiki-config"

# Import after setting the environment variable

from api.main import run_server
run_server()

```

Setting the variable at runtime ensures the configuration loads from your specified directory during the module’s initialization phase.

## Required Configuration Files and Directory Structure

DeepWiki expects up to four JSON configuration files in the custom directory. You only need to include files for settings you wish to override; missing files fall back to internal defaults (with a logged warning).

The expected files are:

- **generator.json** – Defines LLM providers, models, and generation parameters.
- **embedder.json** – Configures embedding models and vectorization settings.
- **lang.json** – Specifies supported languages and localization settings.
- **repo.json** – Sets repository-specific defaults and parsing rules.

Example directory layout:

```

/opt/deepwiki/custom-config/
├── generator.json
├── embedder.json
├── lang.json
└── repo.json

```

Each file follows the same schema as the defaults stored under `api/config/` in the source repository. When `DEEPWIKI_CONFIG_DIR` points to this folder, DeepWiki loads these definitions instead of the bundled versions.

## Summary

- DeepWiki loads JSON configuration files from `api/config/` by default, as defined in [`api/config.py`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/api/config.py).
- Set the **`DEEPWIKI_CONFIG_DIR`** environment variable to override the default location.
- The `load_json_config()` function checks for this variable at lines 103–108, constructing paths with `Path(CONFIG_DIR) / filename` when present.
- You can define the variable in shell sessions, Docker Compose files, or programmatically before importing DeepWiki modules.
- Only include the JSON files you need to override ([`generator.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/generator.json), [`embedder.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/embedder.json), [`lang.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/lang.json), [`repo.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/repo.json)); missing files trigger fallback behavior.

## Frequently Asked Questions

### What is the default configuration directory for DeepWiki?

By default, DeepWiki reads configuration files from the `api/config/` directory relative to the installation location. This is hardcoded as a fallback in [`api/config.py`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/api/config.py) when the `DEEPWIKI_CONFIG_DIR` environment variable is not set.

### Can I use relative paths with DEEPWIKI_CONFIG_DIR?

While the code uses `Path(CONFIG_DIR) / filename`, which accepts relative paths, it is strongly recommended to use absolute paths. Relative paths resolve against the current working directory at runtime, which can lead to inconsistent behavior depending on how the application is launched.

### Which configuration files are required when using a custom directory?

None of the files are strictly required. DeepWiki looks for [`generator.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/generator.json), [`embedder.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/embedder.json), [`lang.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/lang.json), and [`repo.json`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/repo.json), but if a file is missing from the custom directory, the system logs a warning and falls back to internal defaults. You only need to include the files containing settings you wish to override.

### How do I verify that DeepWiki is loading from my custom directory?

Check the application logs at startup. When `DEEPWIKI_CONFIG_DIR` is set, the `load_json_config()` function in [`api/config.py`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/api/config.py) constructs paths using your specified directory. If a configuration file is missing or malformed, the error message will display the full path, confirming whether it originates from your custom location or the default `api/config/` folder.