Installing Apache Superset from PyPI on Linux: when a VM install fits
A VM install with pip fits a team that wants Superset on servers it controls, has Linux administration skills in-house, and expects a small number of users and a modest workload. If you need the supported production path with repeatable builds, a container image or Kubernetes is usually the better fit. Apache Superset is an Apache Software Foundation project released under the Apache License 2.0 (SPDX: Apache-2.0), and the project has no paid edition, so your cost is the infrastructure, the people who run it and any partner work you choose to buy. The software itself carries no license fee.
Before you choose, understand the four components you will be running. The application is a Flask and React web app. It stores its own state in a metadata database, which holds dashboards, charts, users and connection definitions. A caching layer is optional for basic use, but alerts and reports, async queries and dashboard thumbnails depend on it. Celery worker and beat processes are also optional, and most installations running those features use Redis and Celery. The Superset architecture documentation describes how these pieces fit together, and it is the first read before you size the VM.
The PyPI path defaults to SQLite for the metadata database. The project does not recommend SQLite for production, and it tests the application with PostgreSQL and MySQL. Plan a PostgreSQL or MySQL instance from the start, confirm the supported versions for your release in the configuration documentation, and decide who owns its backups. Confirm with your own security team how the VM, its patching and its access to your analytics databases will be governed, because a pip install leaves those controls entirely with you.
Which install components to add and when
This table compares the components a PyPI install of Superset can run with, from the SQLite default to a full set of caching and worker services. Read each row against the features you plan to enable, because the architecture documentation ties alerts, reports, async queries and thumbnails to the caching layer and workers. The main takeaway is that SQLite and the default setup suit evaluation only, and production needs an external metadata database plus Redis and Celery if those features are in scope.
| Component | Role in a PyPI install | When to choose it |
|---|---|---|
| SQLite (default) | Metadata database created by Quickstart and PyPI installs | Local evaluation only. The architecture documentation does not recommend it for production. |
| PostgreSQL or MySQL | External metadata database for users, dashboards and settings | Any production install. Supported versions are PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. |
| Redis caching layer | Optional cache for query and metadata results | Add when you need caching, or as the backend for async queries, alerts and reports. |
| Celery worker | Runs background tasks such as async queries, alerts and reports, and thumbnails | Add when you enable alerts, reports, async queries or dashboard thumbnails. |
| Celery beat | Schedules periodic tasks for the worker | Add alongside Celery workers when scheduled alerts or reports are in use. |
| Gunicorn | WSGI web server that runs the Superset application process | Use for a VM install instead of the development server. Place a reverse proxy in front for TLS. |
Which OS packages and Python version the cryptography library needs
Before you run pip, install the operating system packages that the cryptography library needs. Superset uses this library to encrypt database connection passwords stored in its metadata database, so a missing build dependency will stop the install or leave the encryption layer unusable. The PyPI install guide lists these OS-level dependencies for Debian and Ubuntu, Fedora, and RHEL derivatives. Use the list for your exact distribution and version, not a package set from another release, because package names and availability differ between families. Ask your platform team to confirm which of these packages your build hosts can install from approved repositories, since restricted networks often block the default mirrors.
The Python version is the second check, and it must come from the documentation rather than memory. Confirm the supported interpreter version in the current Superset installation documentation for the release you intend to deploy, and compare it with the Python version your distribution ships. Superset releases change their supported interpreter range, so a version that worked for an earlier release can fail on a newer one. Record the exact Python version and the release number together in your build notes, because you will need both again during upgrades.
Install everything into a dedicated virtual environment owned by the Superset service account. The environment keeps Superset's pinned dependencies separate from system Python packages, which prevents other tools on the VM from changing library versions underneath the application. It also gives you a clean directory to rebuild from if an upgrade fails. Keep the environment path, the Python binary used to create it, and the pip version in your change record, so that a rebuild on a replacement VM reproduces the same dependency tree.
How to install Superset with pip and start it under Gunicorn
This sequence takes a Linux VM from bare operating system to a Superset web application running under Gunicorn on a PostgreSQL or MySQL metadata database. Redis and Celery are added last, only if alerts, reports or async queries are needed.
Install operating system packages
A system administrator installs the Python runtime, pip, the build tools and the OS-level libraries that the cryptography package needs to encrypt database connection passwords. The PyPI install guide lists the package names for Debian, Ubuntu, Fedora and RHEL derivatives, so confirm the names for your distribution against the Superset PyPI install guide. The step is complete when the Python version reported by the interpreter matches the version the guide requires for the Superset release you plan to run.
Create a service user and virtual environment
The administrator creates a dedicated system account for Superset that has no interactive login, along with a directory that holds the application, its configuration and its logs. Inside that directory, create a Python virtual environment so Superset dependencies stay isolated from system Python packages. The check is that the account can activate the environment, upgrade pip inside it, and write to the log directory, while other system users cannot read the configuration directory.
Install apache-superset from PyPI
With the virtual environment active, the administrator installs the apache-superset package from PyPI. Pin the exact release you have tested so that a later install does not pull a newer version. Superset is Apache-2.0 licensed and has no paid edition, so the package itself carries no license purchase. Confirm the installed version with pip show apache-superset and compare it with the release recorded in your change ticket. A mismatch means the upgrade path and the configuration reference in later steps may not match your install.
Set SECRET_KEY and the metadata database
Write superset_config.py with a SECRET_KEY value generated for this environment, and set SQLALCHEMY_DATABASE_URI to a PostgreSQL or MySQL database that you have created for Superset metadata. Superset requires a user-specified SECRET_KEY before it starts, so the process will not run without one. Supported metadata versions are PostgreSQL 10 to 17 and MySQL 5.7 and 8.x, and the default SQLite database is not suitable for production. Store the key outside the code repository, for example in an environment variable or a secrets manager. The check is that Superset starts the Python process without a configuration error.
Run database upgrade and initialization
The administrator runs superset db upgrade to create or migrate the metadata schema, then runs superset init to create default roles and permissions. Take a backup of the metadata database before the first run on an existing database, because the upgrade documentation calls for a backup before any migration. The step is complete when both commands finish without errors, and a second run of superset db upgrade reports nothing left to apply. Record the output so that the migration state is available for later upgrades.
Create an admin user and start Gunicorn
Create the first administrator account with the user creation command in the install guide, using a named account and a strong password stored in your password manager. Then start the application with Gunicorn bound to a local port, so that only the reverse proxy reaches it, and place a reverse proxy with TLS in front of it. Configure the service manager to restart Gunicorn on failure. The check is a local HTTP request to the bound port that returns the login page, followed by a successful login through the proxy hostname with the new administrator account.
Add Redis and Celery when features need them
Skip this step if you do not need alerts, scheduled reports, async queries or dashboard thumbnails. The Superset architecture documentation says these features require a caching layer and worker processes, and most installations use Redis for caching and Celery for workers. Install Redis, add the Celery worker and beat processes as separate services, and point the cache and Celery broker settings at Redis. The check is that a worker reports ready in its logs and that a test async query or manual report run completes and appears in the Superset report history.
Configuration that must be set before first start
Superset will not start until a few settings are defined, and several others decide whether the installation can run reports, async queries and group-based access. Set these in the configuration file before the first launch so the metadata database, caching and login behave the way the rest of this guide assumes.
Define SECRET_KEY explicitly
Superset requires a user-specified SECRET_KEY to start, a requirement that has applied since version 2.1.0. Generate a long random value once, store it in your secrets manager, and load it into the configuration at runtime. Changing it without a plan will invalidate existing sessions and encrypted values. When you rotate it, keep the old value in PREVIOUS_SECRET_KEY until re-encryption is complete, then confirm logins and stored database connections still work.
Point the metadata database URI
The metadata database stores users, dashboards, charts and connection definitions, so it is the first component you must decide. The SQLite default is not suitable for production. Set SQLALCHEMY_DATABASE_URI to a PostgreSQL or MySQL instance you back up, and confirm your server version is on the supported list before you run the database upgrade commands.
Enable caching and Celery
Alerts and reports, async queries and dashboard thumbnails depend on a caching layer and worker processes, which the PyPI install does not provide. Decide whether you will add Redis and Celery now or defer those features, and record that decision. Configure the cache backend and Celery broker in the file so that workers and the web process read the same settings from one place.
Set authentication and role mapping
Superset is built on Flask-AppBuilder and can use LDAP or OAuth2 providers. Choose the authentication type before users sign in, because switching later changes how accounts are created. If your directory holds the access model, map groups to Superset roles with AUTH_ROLES_MAPPING so access is granted by group membership rather than by hand. Confirm the mapping with a test account before you open access.
Locate and version the configuration file
Superset reads its settings from a superset_config.py file, which must be importable by the Python environment that runs the application and workers. Choose a fixed path, such as a directory owned by the service account, and keep it under version control in a repository without secrets. Use the same file for the web process and every worker, or workers will silently run with different settings.
Keep secrets out of the file
The configuration file is Python code, so it should read secrets from environment variables or a secrets store instead of containing literal values. Cover the SECRET_KEY, database password, Redis credentials and OAuth client secrets this way. Restrict file permissions to the service account and confirm that logs and error pages do not print the configuration contents.
How upgrades on a pip install differ from a container
The upgrade sequence for a pip-installed Superset moves the metadata database, the application code and the schema forward in a deliberate order, so you can roll back to a known state if the new release misbehaves. Each step below ends with a check you can record before moving on. The sequence follows the project's upgrade documentation.
Back up the metadata database
Before anything changes, take a full backup of the PostgreSQL or MySQL database that holds Superset's metadata, including users, roles, dashboards, charts, datasets and saved queries. On a pip install, the metadata database is the one piece of state you must be able to restore, because the code lives in a virtual environment you can rebuild. Confirm the backup is restorable by restoring it to a scratch instance or checking the dump file size and restore log. Record the backup location and time so a rollback has a known starting point.
Read UPDATING.md for breaking changes
Open the UPDATING.md file in the Superset repository and read every entry between your current version and the target version. Note changes to configuration keys, removed features, altered database requirements and changed defaults that touch your superset_config.py or your deployment. Your team or DeployOpen can turn these notes into a short change list that the staging test must cover. The output is a written list of required configuration edits, or a confirmed statement that none apply.
Pin the target version in staging
Choose a stable release and pin its exact version in the staging environment rather than installing the latest package. PyPI listed Apache Superset 6.1.0 on May 13, 2026, and the GitHub releases page lists 7.0.0rc2 as a pre-release from October 16, 2026. Pre-releases are for testing, so production should use a stable version that you have validated. Confirm the version you plan to use is marked as a stable release on both PyPI and GitHub before pinning it in your requirements file.
Install the new release into a new virtual environment
Create a fresh virtual environment alongside the current one, then install the pinned version and its dependencies, including the OS packages needed for the cryptography library. Keeping the old environment intact lets you switch back by changing the path your service uses. Run the install with the same Python version your production environment uses, and check that pip reports no dependency conflicts. The output is a second environment that imports superset cleanly and reports the target version.
Apply the configuration changes and run the database upgrade
Apply the superset_config.py edits from the UPDATING.md review, using the same SECRET_KEY as production so existing sessions and encrypted connection passwords remain readable. Then run superset db upgrade against the staging metadata database, which applies the schema migrations for the new release. Watch the output for failed migrations and treat any error as a stop condition. The check is a clean exit with no migration errors, followed by a query showing the Alembic version table at the expected revision.
Run superset init to refresh roles and permissions
Run superset init so Superset recreates or updates its default roles and permissions for the new release. Permission changes in a release can alter what roles can see or do, so review the role list after this step, especially any custom roles and the group mappings you use for SSO. Confirm with a test account from each role that dashboards, datasets and SQL Lab access still match your access model. The output is a documented role check, not just a successful command.
Test staging before switching production
Run the staging instance against the test scenarios your team uses: login, dashboard rendering, chart queries, SQL Lab, dataset refresh and any scheduled reports or async queries. These features depend on the caching and worker components, so test them with those services running. Compare results with the production build where possible. The check is a signed-off test record, and any failed case becomes a fix before the production window.
Repeat the sequence in production and keep the rollback path
Repeat the backup, configuration, install, db upgrade and init steps in production, switching the service to the new environment only after each step passes. Keep the previous virtual environment and the pre-upgrade backup until the new release has run cleanly for an agreed period. If you need to roll back, restore the backup, point the service at the old environment and restart. The output is a running production instance on the pinned version with a recorded rollback procedure.
Limits to confirm before you commit to a VM install
A single-VM install from PyPI is a reasonable starting point, but several limits shape whether it stays workable after go-live. Each card names one limit, what it means for your team, and what to confirm before you commit to this route.
Ongoing Python and OS maintenance
You own the Python runtime, the virtual environment, the OS packages and every dependency update that follows a Superset release. Whoever receives this work needs to track the upgrade guide and UPDATING.md for breaking changes, and to run superset db upgrade and superset init after each upgrade. Confirm who on your team owns patching the host and rehearsing upgrades in staging before production.
Redis and Celery are not included
Alerts and reports, async queries and dashboard thumbnails depend on a caching layer and Celery worker and beat processes. A PyPI install does not bring these up, so you must install, configure and supervise Redis and Celery yourself. Confirm whether these features are in scope for the first release, because they add services to monitor and patch.
Scaling beyond one VM
A single host runs the web application, the metadata database and any workers together unless you split them. Adding capacity means deciding how to run multiple Gunicorn instances behind a load balancer, where the metadata database lives, and how shared cache and workers are reached from each node. Confirm the expected concurrent users and whether a second host is planned before you size this VM.
No Kubernetes path on this route
This route does not produce a Kubernetes deployment. The Helm chart is documented for Kubernetes installs in the 6.1.0 docs but is marked deprecated in current development docs, which point new deployments to the alpha Superset Kubernetes Operator. If your platform standard is Kubernetes, confirm that choice now, since moving a VM install onto a cluster later is a separate migration.
Analytics database drivers installed separately
Superset does not ship drivers for every analytics database. Each database driver is a separate Python package you install into the same virtual environment, and some need OS-level libraries as well. Confirm the exact drivers and versions for each source you connect, and test each connection in staging, since a missing driver often shows up only when a user opens a dataset.
Questions buyers ask before installing Superset from PyPI
How much more effort is a pip install than a container image?
A PyPI install usually takes more hands-on work up front, because your team assembles the Python runtime, system libraries, the web server, the metadata database and any caching or worker components itself. A container image packages most of that once, so the work shifts to building, pinning and scanning the image. Neither route removes the need for a production metadata database, secret management and a tested upgrade routine. The PyPI route suits teams that want direct control of the host, while the container route suits teams already running container platforms. Ask your implementation partner to compare both against your existing build and patch processes before choosing.
Can our own engineers install Superset from PyPI without outside help?
Yes, a capable Linux and Python team can install Superset from PyPI, and the project documents the steps. The harder parts are operational: installing the OS packages that the cryptography library needs, choosing a Python version the release supports, setting a SECRET_KEY, moving the metadata database off the SQLite default, and adding Redis and Celery if you need alerts, reports, async queries or thumbnails. Your team should also own the upgrade routine and the backup schedule. Outside help is most useful when the team has no one to take those responsibilities on, or when the deployment must meet specific compliance or network constraints.
What does an outside implementation cover, and what does it need from our team?
A fixed-scope engagement typically covers the agreed installation on your infrastructure, the metadata database and web server setup, configuration of authentication and TLS as scoped, the optional caching and worker components, backup and upgrade runbooks, and documentation handover. Your team usually provides access to the target Linux hosts and cloud or data center accounts, the database and identity provider details, decisions on user access and data sources, a staging environment, and a named technical owner who can approve changes. Ask for the written scope to list each deliverable and each dependency on your side before work starts.
What drives the cost of a Superset installation up or down?
Cost follows the scope agreed in writing. The main drivers are the number of components (web application only, or also Redis, Celery workers and beat for alerts and reports), the number and type of database connections and identity integrations, whether you need a separate staging environment, the number of hosts and environments to configure consistently, and the amount of hardening, documentation and handover you request. One-time work covers design, installation and handover. Recurring costs cover patching, upgrades, monitoring and any retainer you add for support. Ask for a quote that separates one-time and recurring items, names the environments included, and lists the assumptions about your infrastructure.
Is PyPI or Docker the better choice for a production Superset?
Neither route is inherently better for production, because the deciding factors are your platform and operating model. The PyPI route gives direct control over the host and suits teams that manage virtual machines well. The Docker route packages dependencies and makes repeatable builds easier, but the project's own architecture guidance says the SQLite default and the Docker Compose PostgreSQL container are not recommended for production. Whichever you choose, you need an external PostgreSQL or MySQL metadata database, a SECRET_KEY, backups and a staging path for upgrades. Confirm the supported metadata database versions and your Python version against the current documentation before you commit.
How are Superset upgrades handled after the first install?
Upgrades follow the project's documented sequence: back up the metadata database, test the new version in staging, read UPDATING.md for breaking changes between versions, run the database upgrade command, then run the initialization step. Each release can change configuration or behavior, so the upgrade should be treated as a planned change, not a routine package update. Confirm with your partner whether upgrade runbooks, a staging rehearsal and post-upgrade checks are included in the scope or offered as a recurring retainer. Ask who approves the change and who holds the rollback plan.
When to move from a VM to Docker Compose or Kubernetes
A VM install of Superset from PyPI is a reasonable place to start, but it is not the only supported path, and the move to a container platform is a decision to make on purpose rather than one that happens after an outage. The question to answer first is whether your team will own container images, orchestration and upgrades, because each path adds work that a pip install on a VM does not. Two sibling topics cover the first two options in depth: building a production Docker image, which covers extending the official image with your database drivers and pinning and scanning the result, and running Superset with Docker Compose, which covers where Compose fits and where it stops. Read both before deciding, since a Compose setup still needs an external metadata database, backups, TLS and custom images.
Kubernetes needs a more careful check because the project's guidance has changed. The Superset 6.1.0 documentation describes installs with the official Helm chart, but the current development documentation marks that chart as deprecated and points new deployments to the Apache Superset Kubernetes Operator. That operator is in alpha, uses a v1alpha1 API, and its custom resource schemas may change between releases. Before choosing Kubernetes, confirm with the project which install method is recommended for the release you plan to run, whether the operator is still alpha, and what upgrade path it documents for schema changes. Ask your platform team whether they are prepared to track breaking changes in a pre-stable operator and to test each change in staging first.
