Superset Configuration Loading#

Superset's runtime configuration is built in two layers: defaults defined in superset/config.py and local overrides applied at the end of that same file from a user-supplied superset_config.py. Every uppercase name in the override file is merged into the running module — no restart machinery, no separate config system 1.

How the config file is located#

At the tail end of superset/config.py, after all defaults are declared, Superset tries two discovery strategies in priority order 2:

SUPERSET_CONFIG_PATH set?
  ├─ YES → load file at that path via importlib (ignores PYTHONPATH)
  └─ NO → is "superset_config" importable on PYTHONPATH?
              ├─ YES → from superset_config import *
              └─ NO → no override, defaults only

1. SUPERSET_CONFIG_PATH (explicit file path)#

Set SUPERSET_CONFIG_PATH to the absolute path of your config file 3:

export SUPERSET_CONFIG_PATH=/app/superset_config.py

Superset uses importlib.util.spec_from_file_location to load the file directly — the file does not need to be on sys.path 4. Only keys where key.isupper() are copied into the running superset.config module 5. This method is explicitly designed for environments like pex where PYTHONPATH manipulation is impractical.

In a custom Dockerfile built on the official Superset image 3:

COPY --chown=superset superset_config.py /app/
ENV SUPERSET_CONFIG_PATH /app/superset_config.py

2. PYTHONPATH discovery (module import)#

If SUPERSET_CONFIG_PATH is not set, Superset checks whether a superset_config module is importable (importlib.util.find_spec("superset_config")). If found, it does a wildcard from superset_config import * 6. Place your superset_config.py anywhere on sys.path — commonly alongside the working directory or in a custom Python path entry.

Both strategies print the resolved file path to the console in cyan on successful load 7 8, making it easy to verify which file was picked up.

The SUPERSET_CONFIG env var (full module override)#

A separate, less-common escape hatch exists in create_app(): setting SUPERSET_CONFIG replaces the entire base config module (default "superset.config") before any Flask config is loaded 9. This is a lower-level override and is rarely needed.

Important implementation details#

• Placement matters. The comment at line 1972–1976 warns: "Don't add config values below this line since local configs won't be able to override them." All defaults must appear before the override block.
• Only uppercase names are merged when using SUPERSET_CONFIG_PATH. The PYTHONPATH path uses import *, which respects __all__ if defined 5 10.
• superset_config.py is a Flask config module. It can configure Flask itself, Flask-WTF, flask-caching, flask-migrate, and Flask-AppBuilder settings — not only Superset-specific keys 3.
• Docker Compose dev setup. The docker/pythonpath_dev/superset_config.py file auto-imports a git-ignored superset_config_docker.py for local overrides, demonstrating the PYTHONPATH pattern in practice 11.

Key files#

Reference#

• Official configuration docs 3
• CONFIG_PATH_ENV_VAR = "SUPERSET_CONFIG_PATH" — the constant used in the override block