Docker Image Build#

Superset's Dockerfile uses a multi-stage build to produce three primary images — lean, dev, and ci — plus internal helper stages. All Python package installations are handled through docker/pip-install.sh, which wraps uv pip install and optionally installs/removes build-essential to keep final image sizes small 1.

Stage Overview#

The build graph looks like this:

python:3.11-slim-bookworm
  └─ python-base (uv venv, bash scripts)
       ├─ python-translation-compiler (pybabel, .mo files)
       └─ python-common (system libs, frontend assets, superset source)
            ├─ lean ← production image
            │ └─ ci ← lean + postgres driver
            └─ dev ← development image

Stage Details#

python-base 2#

Establishes the Python runtime. Creates a superset OS user 3, installs uv via pip, creates /app/.venv, and copies all docker/*.sh scripts into /app/docker/ 4.

No environment variables are set here; those are defined in python-common.

python-common 5#

The shared base for all three final images. Responsibilities:

• Sets FLASK_APP, PYTHONPATH, SUPERSET_PORT=8088, SUPERSET_ENV=production 6.
• Installs system APT libraries: curl, libsasl2-dev, libpq-dev, libecpg-dev, libldap2-dev 7.
• Installs Playwright with Chromium by default (INCLUDE_CHROMIUM=true, INCLUDE_FIREFOX=false).
• Copies compiled frontend assets from the superset-node stage 8.
• Copies all of superset/ source and merges compiled .mo translation files from both frontend and backend translation stages 9.
• Sets the default CMD to /app/docker/entrypoints/run-server.sh 10.

lean — Production Image 11#

Installs requirements/base.txt via pip-install.sh --requires-build-essential, installs the superset package (uv pip install .), and pre-compiles Python bytecode (python -m compileall) 12. Drops to the superset user.

This is the image published to Docker Hub and used as the base for custom deployments.

ci — CI Image 13#

Extends lean. Adds uv pip install .[postgres] as root, then drops back to the superset user. Overrides CMD to /app/docker/entrypoints/docker-ci.sh 14.

dev — Development Image 15#

Extends python-common (not lean). Adds git, pkg-config, default-libmysqlclient-dev 16, copies all requirements/*.txt files, and installs requirements/development.txt (which includes test and lint tooling). Also installs .[postgres] 17. Default CMD is the same as python-common (run-server.sh), but it is normally invoked via docker-bootstrap.sh in Docker Compose.

Build Arguments#

Frontend Build Stage#

The Node stages (superset-node-ci → superset-node) run on the build host's native platform (--platform=${BUILDPLATFORM}) 24. npm ci installs dependencies; npm run ${BUILD_CMD} produces /app/superset/static/assets. The compiled assets are then COPY --from=superset-node into python-common 8.

Runtime Bootstrap (docker-bootstrap.sh)#

For Docker Compose deployments, containers are started via docker/docker-bootstrap.sh rather than the default CMD. At startup it:

1. If DEV_MODE=true, reinstalls the app in editable mode (uv pip install -e .) 25.
2. If DATABASE_DIALECT starts with postgres, installs .[postgres] 26.
3. If /app/docker/requirements-local.txt exists, installs it with uv pip install --no-cache-dir -r 27.
4. Routes to app (Flask dev server), app-gunicorn, worker (Celery), or beat based on the first CLI argument 28.

Extending the Published Image#

Three patterns are supported:

1. docker/requirements-local.txt (no Dockerfile change, recommended for local dev)
Create ./docker/requirements-local.txt with additional packages and run docker compose up. docker-bootstrap.sh installs this file at container start 27. This file is git-ignored by convention.

2. Extend lean in a custom Dockerfile (recommended for production)

FROM apache/superset:latest
USER root
COPY requirements-local.txt .
RUN uv pip install -r requirements-local.txt
USER superset

The lean image is the right extension point — it contains pinned production dependencies from requirements/base.txt 29.

3. pyproject.toml optional extras (outside Docker)
For non-Docker installs, use pip install "apache-superset[postgres,mysql]". The full list of 40+ optional extras (BigQuery, Snowflake, Trino, etc.) is defined in pyproject.toml.

Key Files Reference#