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

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 reads the environment variable on line 55:

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

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:

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:

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:

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.
• 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, embedder.json, lang.json, 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 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, embedder.json, lang.json, and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}