Apache Superset

6.0.0 · active · verified Thu Apr 16

Apache Superset is a modern, enterprise-ready business intelligence web application for data exploration and visualization. It supports a wide array of databases via SQLAlchemy, offering a no-code chart builder, a powerful SQL editor, and dynamic dashboards. The library is actively maintained, with major releases following a time-based schedule to provide predictable updates and supporting the latest minor versions of the last two major releases.

Common errors

```
Error: pg_config executable not found.
```
cause When installing `psycopg2` (the PostgreSQL driver) as part of `apache-superset[postgresql]`, the system is missing PostgreSQL development headers, which `psycopg2` needs to compile.

fix Install PostgreSQL development libraries on your system (e.g., `sudo apt-get install libpq-dev` on Debian/Ubuntu, `sudo yum install postgresql-devel` on CentOS/RHEL, or ensure PostgreSQL is installed and its `bin` directory is in `PATH` on macOS).
```
RuntimeError: Working outside of application context.
```
cause This error typically occurs when running Superset CLI commands (like `superset db upgrade` or `superset init`) without properly setting the `FLASK_APP` environment variable to `superset` and `SUPERSET_CONFIG_PATH` to your configuration file.

fix Before running Superset CLI commands, set environment variables: `export FLASK_APP=superset` and `export SUPERSET_CONFIG_PATH=/path/to/your/superset_config.py`.
```
validating superset\docker-compose-image-tag.yml: services.superset-worker-beat.env_file.0 must be a string
```
cause This error indicates that your Docker Compose version is outdated. The `env_file` syntax in `docker-compose.yml` has changed in newer Docker Compose versions.

fix Update your Docker Compose to a recent version. If using `docker-compose` command, consider migrating to `docker compose` (without the hyphen) as it's the newer CLI for Docker Compose V2.
```
Table 'columns' has an 'extra' column, which is unsupported by the 'Presto' dialect.
```
cause Certain database dialects (like Presto) do not support all SQLAlchemy features or metadata columns used by Superset's internal ORM definitions. This can happen when connecting a database with unsupported column properties.

fix Check the official Superset documentation for specific database connection requirements and known limitations. You may need to create a custom SQLAlchemy dialect or view to abstract away unsupported features for that specific database.

Warnings

breaking Apache Superset 6.0.0 upgrades to Flask-AppBuilder 5.0.0, which removes the deprecated `AUTH_OID` authentication type. Users relying on OpenID must migrate to OAuth, LDAP, or database authentication before upgrading.
Fix: Migrate your authentication configuration from OpenID to OAuth, LDAP, or database authentication methods.
breaking Older versions of Apache Superset (up to 2.0.1) had a critical vulnerability (CVE-2023-27524) due to a predictable default Flask `SECRET_KEY`. Installations that have not modified this key are at risk of authentication bypass and remote code execution.
Fix: Always generate and configure a strong, random `SECRET_KEY` in `superset_config.py`. Superset versions 2.1.0 and later prevent startup with the default key.
gotcha A critical access control flaw (CVE-2026-XXXX) found in versions up to 4.1.3 allows low-privileged users to infer and enumerate data from restricted datasets by crafting specific Row Level Security (RLS) filter clauses containing subqueries.
Fix: Apply security updates and patches once the Apache Superset team releases a fix addressing this RLS bypass vulnerability.
gotcha Users frequently report slow performance, SQL execution hang-ups, and difficulties with complex queries involving multiple joins in Superset. This can stem from inefficient database queries, large datasets, or lack of proper caching.
Fix: Optimize SQL queries (select only needed columns, simplify joins), implement an efficient caching layer (e.g., Redis), and evaluate database performance for analytical workloads.

Install

pip install apache-superset Install core library
pip install 'apache-superset[postgresql,mysql]' # Install with common database drivers Install with optional database drivers

Quickstart

This quickstart outlines the steps to install and run Apache Superset locally using pip and its CLI commands. Note that for a full-featured sandbox environment, especially for development, the official documentation often recommends using Docker Compose.

# Create and activate a Python virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Apache Superset and a database driver (e.g., SQLite for quickstart)
pip install apache-superset

# Generate a SECRET_KEY and initialize Superset
SECRET_KEY=$(python -c 'import os; print(os.urandom(64).decode("latin-1"))')
echo "SECRET_KEY = '$SECRET_KEY'" > superset_config.py
export SUPERSET_CONFIG_PATH=./superset_config.py
export FLASK_APP=superset
superset db upgrade
superset fab create-admin --username admin --password admin --firstname admin --lastname admin --email admin@example.com
superset init

# Run the Superset web server
superset run -p 8088 --with-threads --reload --debugger --debug

# Access Superset at http://localhost:8088 with admin/admin

view raw JSON →