Installing Superset from PyPI
This page describes how to install Superset using the apache-superset
package published on PyPI.
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
In Ubuntu 20.04 and 22.04 the following command will ensure that the required dependencies are installed:
sudo apt-get install build-essential libssl-dev libffi-dev python3-dev python3-pip libsasl2-dev libldap2-dev default-libmysqlclient-dev
In Ubuntu before 20.04 the following command will ensure that the required dependencies are installed:
sudo apt-get install build-essential libssl-dev libffi-dev python-dev python-pip libsasl2-dev libldap2-dev default-libmysqlclient-dev
Fedora and RHEL-derivative Linux distributions
Install the following packages using the yum
package manager:
sudo yum install gcc gcc-c++ libffi-devel python-devel python-pip python-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. Python ships with
virtualenv
out of the box. If you're using pyenv, you can install pyenv-virtualenv. Or you can install it with pip
:
pip install virtualenv
You can create and activate a virtual environment using:
# 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
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 --debugger
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.