TVL Managed Superset
Get started

Install Apache Superset: Step-by-Step 2026 Guide

Complete guide to install Apache Superset locally and in production: Docker, Python, Kubernetes. All steps detailed.

· Tuvalu Tech OÜ

Installing Apache Superset in 2026 can take 5 minutes or 2 days depending on the method. This step-by-step guide covers the three recommended approaches: Docker installation for testing, Python installation to develop a connector, and Kubernetes deployment for production. Each step is documented with exact commands and pitfalls to avoid.

1. Common prerequisites

Whatever the method, you'll need:

  • A Linux, macOS or Windows (with WSL2) machine;
  • 4 GB RAM minimum for testing (8 GB recommended);
  • 10 GB free disk space;
  • Internet access to fetch images / packages.

If you want to skip these steps and get a pre-configured instance, TVL Managed Superset deploys a ready-to-use instance in less than 3 minutes.

2. Method 1 — Docker installation (recommended for testing)

2.1 Install Docker and Docker Compose

On Ubuntu:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

On macOS, install Docker Desktop. On Windows, same with WSL2 enabled.

2.2 Clone the official repo

git clone https://github.com/apache/superset
cd superset
git checkout 5.0.0  # or the latest stable

2.3 Launch Superset

The official repo offers two Docker compositions. For a production-like environment (no hot reload):

docker compose -f docker-compose-non-dev.yml up -d

First time, image download and initialization takes 3 to 5 minutes. Track progress with:

docker compose -f docker-compose-non-dev.yml logs -f superset_app

Wait for Loaded your LOCAL configuration and Booting worker with pid.

2.4 Log in

Open browser at http://localhost:8088. Default credentials:

  • Login: admin
  • Password: admin

Change this password immediately via the user menu top-right. Even locally, it avoids accidents.

2.5 Load example datasets

docker exec -it superset_app superset load-examples

Three demo dashboards will appear under the "Dashboards" tab.

3. Method 2 — Python installation (for developers)

Suitable if you want to modify source code, write a custom connector, or contribute upstream.

3.1 Prepare Python environment

python3.10 -m venv ~/.venvs/superset
source ~/.venvs/superset/bin/activate
pip install --upgrade pip wheel

Note: Superset 5.x requires Python 3.10 or 3.11. Python 3.12 works but some drivers (psycopg2-binary) may have compilation issues.

3.2 Install system dependencies

On Ubuntu:

sudo apt-get install -y build-essential libssl-dev libffi-dev \
  python3-dev libsasl2-dev libldap2-dev default-libmysqlclient-dev

3.3 Install Apache Superset

pip install apache-superset
pip install psycopg2-binary  # Postgres driver

3.4 Configure SECRET_KEY

Superset refuses to start without a strong secret key. Generate it:

export SUPERSET_SECRET_KEY=$(openssl rand -base64 42)
export FLASK_APP=superset

3.5 Initialize the metadata database

superset db upgrade
superset fab create-admin \
  --username admin \
  --firstname Admin \
  --lastname User \
  --email admin@example.com \
  --password 'ChangeMe!2026'
superset init

3.6 Run the server

superset run -p 8088 --with-threads --reload --debugger

For a multi-process setup locally (production-equivalent):

gunicorn -w 4 -k gthread -b 0.0.0.0:8088 \
  --timeout 120 "superset.app:create_app()"

4. Method 3 — Kubernetes deployment (production)

4.1 Cluster prerequisites

You need a Kubernetes 1.25+ cluster with:

  • Helm 3.10+;
  • An ingress controller (ingress-nginx recommended);
  • Cert-manager for automatic HTTPS;
  • A StorageClass capable of provisioning dynamic PVCs.

4.2 Add the Helm repo

helm repo add superset https://apache.github.io/superset
helm repo update

4.3 Prepare values

Create a values-prod.yaml file:

postgresql:
  enabled: false
redis:
  enabled: false

supersetNode:
  connections:
    db_host: my-postgres.db.cloud.example
    db_port: "5432"
    db_user: superset
    db_pass: SECRET
    db_name: superset
    redis_host: my-redis.cache.cloud.example
    redis_port: "6379"

ingress:
  enabled: true
  hosts:
    - superset.example.com
  tls:
    - hosts: [superset.example.com]
      secretName: superset-tls

bootstrapScript: |
  #!/bin/bash
  set -eu
  uv pip install psycopg2-binary authlib

The bootstrapScript with uv pip install fixes a known trap: Superset 5.0 uses a venv and standard pip installation lands beside it.

4.4 Install the chart

helm install superset superset/superset \
  -n superset --create-namespace \
  -f values-prod.yaml \
  --version 0.15.2 --timeout 10m

4.5 Verify deployment

kubectl get pods -n superset
kubectl logs -n superset deploy/superset --tail=50

If a pod stays in Init:Error, check the init container log: kubectl logs <pod> -n superset -c init-superset-db. Typical causes: bad DB URI, firewall blocking Postgres port, or unaccepted SSL certificate.

5. Post-installation configuration

5.1 Connect your first database

In the UI: Settings → Database Connections → + Database. Choose your type (PostgreSQL, MySQL, BigQuery, etc.), enter the SQLAlchemy URI, test the connection, save.

PostgreSQL format: postgresql+psycopg2://user:pass@host:5432/dbname.

5.2 Enable Redis cache

In superset_config.py:

CACHE_CONFIG = {
    "CACHE_TYPE": "RedisCache",
    "CACHE_DEFAULT_TIMEOUT": 300,
    "CACHE_KEY_PREFIX": "superset_",
    "CACHE_REDIS_URL": "redis://redis:6379/1",
}
DATA_CACHE_CONFIG = CACHE_CONFIG

5.3 Configure email sending

For alerts and scheduled reports:

SMTP_HOST = "smtp.example.com"
SMTP_PORT = 587
SMTP_STARTTLS = True
SMTP_USER = "alerts@example.com"
SMTP_PASSWORD = "..."
SMTP_MAIL_FROM = "alerts@example.com"

5.4 Enable useful feature flags

FEATURE_FLAGS = {
    "DASHBOARD_RBAC": True,
    "EMBEDDED_SUPERSET": True,
    "ALERT_REPORTS": True,
    "DASHBOARD_CROSS_FILTERS": True,
}

6. Common errors and solutions

"ModuleNotFoundError: No module named 'psycopg2'"

You're running Superset 5.x in Docker or Kubernetes. The official image uses a venv at /app/.venv/ and standard pip install lands beside it. Solution: use uv pip install psycopg2-binary in bootstrap.

"Could not connect to redis"

The Redis URL in CACHE_CONFIG doesn't point to a reachable Redis. Check the hostname (in Docker: redis, not localhost) and port.

"SECRET_KEY too short"

Since Superset 4.x, the key must be at least 32 characters. Regenerate with openssl rand -base64 42.

"CSRF session token is missing"

You access Superset via two different URLs (with and without www, or HTTP and HTTPS mixed). Force a canonical URL at the ingress level and use WTF_CSRF_ENABLED = True in production.

7. What to do after installation?

  1. Connect your first database (see our comparison and the PostgreSQL guide);
  2. Create your first dashboard;
  3. Configure roles and users;
  4. Set up metadata DB backups;
  5. Document your incident runbook.

8. When to switch to a managed service?

If after installation you spend more than 4h/month maintaining the instance, the economic calculation tilts toward managed. This configuration is automatically managed by TVL Managed Superset, applying best practices by default and freeing your time for dashboard creation.

9. Recommended architecture per environment

Development environment

Docker Compose on a local machine or VPS. All-in-one: Superset, Postgres, Redis, Celery workers in the same docker-compose.yml. No HA, no SSL, no monitoring. Goal: iteration speed only.

Staging environment

Identical to production but on half-half resources. Connected to an anonymized copy of the production database. Used to validate updates, new critical dashboards, and dbt migrations before deployment.

Production environment

Kubernetes with high availability, managed HA Postgres database, managed Redis, ingress with HTTPS, Prometheus monitoring, verified daily backups, up-to-date incident runbook. Going to production requires checking the 25-point checklist.

10. FAQ

Which Python version to use?

Apache Superset 5.x officially supports Python 3.10 and 3.11. Python 3.12 works but may have compilation issues for psycopg2-binary. Avoid Python 3.9 (deprecated for Superset 5.x).

Dedicated server or cluster?

Below 30 concurrent users, a single Docker server suffices. Beyond, or for high availability, Kubernetes deployment with multiple replicas becomes necessary.

How to evolve a Docker instance to Kubernetes?

Backup the Postgres metadata DB (pg_dump), redeploy on Kubernetes via the Helm chart pointing to the same DB, verify the instance restarts correctly. The transition takes about half a day for a modest instance.

Why does my Docker installation crash at startup?

Most frequent causes: SECRET_KEY too short or missing, port 8088 already in use, insufficient resources (less than 4 GB RAM available), or metadata DB not initialized. Check each container's logs with docker compose logs.

Is dev mode suitable for production?

No. The dev docker-compose.yml enables hot reload, disables some optimizations, and has no security hardening. Always use docker-compose-non-dev.yml or the Helm chart for production.

Want the benefits of Apache Superset without the friction of installation and maintenance? Deploy your instance in 3 clicks with TVL Managed Superset, hosted in Europe (OVHcloud, Roubaix, France).