Installing Superset from PyPI
This page describes how to install Superset using the apache_superset package published on PyPI.
Python Compatibility
The minimum Python version is 3.11. The Python version classifiers in
pyproject.toml
list the officially supported versions; the open-ended requires-python lower
bound does not certify every newer interpreter.
The source checkout includes experimental Python 3.15 compatibility. Its package
requirements select NumPy >=2.5.4,<2.6 and pandas >=3.1.0,<3.2 on Python 3.15
and newer. Python 3.11 through 3.14 retain NumPy >=1.23.5,<2.5 and pandas
>=2.3.3,<2.4; the minimum Python version has not changed. These source changes
do not imply that an already published PyPI release supports Python 3.15.
The focused
compatibility workflow
tests Python 3.11 through 3.15. It installs the application without dependency
overrides, checks dependency consistency, migrates a fresh SQLite metadata
database, checks /health, and runs engine metadata, pandas post-processing
(including Prophet), result-set, importer utility, model helper, cursor, join,
Docker configuration, and core SDK tests. This focused selection does not
establish support for every optional database or feature.
For Python 3.15 testing, install from the source checkout's package metadata, rather than applying the generated Python 3.11 requirement pins:
python -m pip install -e ./superset-core -e .
Run this command from the repository root in an isolated Python 3.15 environment. Some dependencies require source builds, so a working C/C++ toolchain may be needed. On Windows, install compatible C/C++ build tools. The generated requirement files remain tied to the existing Python 3.11 deployment baseline and are not Python 3.15 lock files.
When building the repository's lean or superset Docker target with a Python
3.15 base image, the application dependency stage installs both local packages
from their metadata instead of applying the Python 3.11 pins. Older interpreters
retain the requirements-based installation. This does not change the default
image's Python version or establish Python 3.15 support for every Docker target;
the development target still uses its generated development requirements.
Container acceptance must include the complete image build, dependency consistency,
fresh metadata migration, authentication, and the workloads needed by the deployment.
A complete Python 3.15 image build has not been verified by this focused workflow;
a dependency-only image build is not a substitute for that acceptance. The image's
/health endpoint is a liveness check, not proof that PostgreSQL, Redis, or queued
work is available; verify those workflows separately in readiness monitoring.
For deployment-specific shutdown validation, send SIGTERM to the Gunicorn master
and allow more than its configured graceful timeout before escalating. Validate
worker exits as well as the master's exit code. Gunicorn gthread workers can
encounter a keepalive-drain issue requiring deadline escalation after requests.
An alternative to evaluate for the deployment is
SERVER_WORKER_CLASS=sync with SERVER_THREADS_AMOUNT=1; setting only the worker
class while retaining multiple threads can select gthread again. Synchronous
workers have different concurrency characteristics, so capacity must be measured
for that configuration.
The focused workflow is not a full production certification. The full
database-driver matrix, integration and browser workflows, live report delivery,
and screenshot generation require deployment-specific validation. Production
acceptance must also cover the target deployment's authentication, secrets,
network/TLS configuration, workload, backup/restore, and availability requirements.
Windows does not provide extended longdouble precision and has Unix-signal
type-checking limitations.
Use an officially supported Python version for production deployments until
these broader compatibility checks have been completed.
OS Dependencies
Superset stores database connection information in its metadata database. For that purpose, we use the cryptography Python library to encrypt connection passwords. Unfortunately, this library has OS level dependencies.
Debian and Ubuntu
The following command will ensure that the required dependencies are installed (tested on Ubuntu 20.04, 22.04, and 24.04):
sudo apt-get install build-essential libssl-dev libffi-dev python3-dev python3-pip python3-venv libsasl2-dev libldap2-dev libpq-dev default-libmysqlclient-dev pkg-config
Refer to the
pyproject.toml file for the list of
Python versions officially supported by Superset, and install a matching python3 interpreter for
your distribution. The libpq-dev package is only needed if you intend to connect to (or use) a
PostgreSQL database; you can omit it otherwise.
Fedora and RHEL-derivative Linux distributions
Install the following packages using the yum package manager:
sudo yum install gcc gcc-c++ libffi-devel python3-devel python3-pip python3-wheel openssl-devel cyrus-sasl-devel openldap-devel
In more recent versions of CentOS and Fedora, you may need to install a slightly different set of packages using dnf:
sudo dnf install gcc gcc-c++ libffi-devel python3-devel python3-pip python3-wheel openssl-devel cyrus-sasl-devel openldap-devel
Also, on CentOS, you may need to upgrade pip for the install to work:
pip3 install --upgrade pip
Mac OS X
If you're not on the latest version of OS X, we recommend upgrading because we've found that many issues people have run into are linked to older versions of Mac OS X. After updating, install the latest version of XCode command line tools:
xcode-select --install
We don't recommend using the system installed Python. Instead, first install the homebrew manager and then run the following commands:
brew install readline pkg-config libffi openssl mysql postgresql@14
You should install a recent version of Python. Refer to the pyproject.toml file for a list of Python versions officially supported by Superset. We'd recommend using a Python version manager like pyenv (and also pyenv-virtualenv).
Let's also make sure we have the latest version of pip and setuptools:
pip install --upgrade setuptools pip
Lastly, you may need to set LDFLAGS and CFLAGS for certain Python packages to properly build. You can export these variables with:
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CFLAGS="-I$(brew --prefix openssl)/include"
These will now be available when pip installing requirements.
Python Virtual Environment
We highly recommend installing Superset inside of a virtual environment.
You can create and activate a virtual environment using the following commands. Ensure you are using a compatible version of python. You might have to explicitly use for example python3.11 instead of python3.
# virtualenv is shipped in Python 3.6+ as venv instead of pyvenv.
# See https://docs.python.org/3.6/library/venv.html
python3 -m venv venv
. venv/bin/activate
Or with pyenv-virtualenv:
# Here we name the virtual env 'superset'
pyenv virtualenv superset
pyenv activate superset
Once you activated your virtual environment, all of the Python packages you install or uninstall
will be confined to this environment. You can exit the environment by running deactivate on the
command line.
Installing and Initializing Superset
First, start by installing apache_superset:
pip install apache_superset
Then, define mandatory configurations, SECRET_KEY and FLASK_APP:
export SUPERSET_SECRET_KEY=YOUR-SECRET-KEY # For production use, make sure this is a strong key, for example generated using `openssl rand -base64 42`. See https://superset.apache.org/admin-docs/configuration/configuring-superset#specifying-a-secret_key
export FLASK_APP=superset
Then, you need to initialize the database:
superset db upgrade
Finish installing by running through the following commands:
# Create an admin user in your metadata database (use `admin` as username to be able to load the examples)
superset fab create-admin
# Load some data to play with
superset load_examples
# Create default roles and permissions
superset init
# To start a development web server on port 8088, use -p to bind to another port
superset run -p 8088 --with-threads --reload
# For debugging with interactive console (⚠️ localhost only)
# superset run -p 8088 --with-threads --reload --debugger
The --debugger flag enables Werkzeug's interactive console at /console. Only use this for local development and never bind to 0.0.0.0 or expose the server to networks when debugging is enabled.
If everything worked, you should be able to navigate to hostname:port in your browser (e.g.
locally by default at localhost:8088) and login using the username and password you created.