---
title: PyPI
hide_title: true
sidebar_position: 4
version: 1
---

import useBaseUrl from "@docusaurus/useBaseUrl";

# Installing Superset from PyPI

<img src={useBaseUrl("/img/pypi.png" )} width="150" />
<br /><br />

This page describes how to install Superset using the `apache_superset` package [published on PyPI](https://pypi.org/project/apache_superset/).

## 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**

Ubuntu **24.04** uses python 3.12 per default, which currently is not supported by Superset. You need to add a second python installation of 3.11 and install the required additional dependencies.
```bash
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-dev python3.11-venv build-essential libssl-dev libffi-dev libsasl2-dev libldap2-dev default-libmysqlclient-dev
```

In Ubuntu **20.04 and 22.04** the following command will ensure that the required dependencies are installed:

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
xcode-select --install
```

We don't recommend using the system installed Python. Instead, first install the
[homebrew](https://brew.sh/) manager and then run the following commands:

```bash
brew install readline pkg-config libffi openssl mysql postgresql@14
```

You should install a recent version of Python. Refer to the
[pyproject.toml](https://github.com/apache/superset/blob/master/pyproject.toml) file for a list of Python
versions officially supported by Superset. We'd recommend using a Python version manager
like [pyenv](https://github.com/pyenv/pyenv)
(and also [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv)).

Let's also make sure we have the latest version of `pip` and `setuptools`:

```bash
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:

```bash
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`.

```bash
# 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:

```bash
# 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`:

```bash
pip install apache_superset
```

Then, define mandatory configurations, SECRET_KEY and FLASK_APP:
```bash
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/docs/configuration/configuring-superset#specifying-a-secret_key
export FLASK_APP=superset
```

Then, you need to initialize the database:

```bash
superset db upgrade
```

Finish installing by running through the following commands:

```bash
# 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.