Apache Superset Python version requirements by release: what changes and when
If your team runs Superset on Python 3.9 or 3.10, the runtime needs its own upgrade decision, separate from the Superset release you choose. Python 3.11 is the version to plan for. Superset 5.0 deprecated Python 3.9 and recommended 3.11 while keeping 3.10 supported across the 5.0 lifecycle. Python 3.10 remains supported through the 5.x and 6.x lines, but the UPDATING notes after 6.1.0 remove 3.10 support and require Python 3.11 or higher. A Superset upgrade that stays on 3.10 today may therefore not be a stable path for the next major line.
The dated releases give you a timeline to work from. Apache Superset 6.0.0 was published on December 18, 2025, and 6.1.0 followed on May 13, 2026, according to PyPI. The GitHub releases page lists 7.0.0rc2 as a pre-release dated October 16, 2026. A release candidate is not a final requirements statement, so confirm the 7.0 Python minimum against the final release notes and the UPDATING.md entries that ship with it before you commit a date. Check the apache/superset releases page and the UPDATING.md file at the time you plan.
Treat the interpreter as a dependency with its own test cycle. The Python version constrains your PyPI install, the base image you build from and every database driver in your virtual environment or container, so a driver that lacks wheels for 3.11 can block the move even when Superset itself is ready. Inventory the drivers you load, confirm each supports your target interpreter, and rebuild and test the environment in staging. Teams that build custom images should also confirm the image-level changes in the separate Docker image topic before cutting over.
Which Python version each Superset release line expects
This table maps each Superset release line to its Python guidance, the effect on your team, and the action to take before you upgrade. Read it from the top down against the version you run today and the version you plan to reach. The main takeaway is that 3.11 is the safe target now, and 3.10 support ends with the release after 6.1.0.
| Release line | Python guidance | Impact on the team | Action needed |
|---|---|---|---|
| Superset 5.0 | Python 3.9 deprecated, 3.11 recommended, 3.10 still supported | Teams on 3.9 must plan a runtime change before moving to this line | Move hosts, base images and drivers to 3.11 where possible |
| Superset 5.x and 6.x | Python 3.10 supported | 3.10 works, but it is the older runtime and the one that is being removed | Use 3.11 for new builds and confirm your drivers support it |
| Release after 6.1.0 | Python 3.10 removed, 3.11 or higher required | Any 3.10 environment will not run this release | Rebuild the runtime on 3.11 or higher in staging before upgrading production |
| Superset 7.0 (pre-release) | Release candidate listed on GitHub; confirm final minimum before planning | Minimum version may change before the final release | Check the final UPDATING.md notes and release page before fixing a runtime |
| PyPI installs | Python version must match the release line you install | pip resolves the package, but the interpreter version is your responsibility | Pin the interpreter version and test the install in a clean virtual environment |
| Base container images | Image Python version must match the release | Custom images built on older Python tags will fail on newer releases | Rebuild images on a 3.11 base and rescan after each change |
| Database drivers | Each driver package has its own Python support range | A driver that lags behind may block the upgrade | Confirm driver versions for your warehouses against the target Python before testing |
Why the Python runtime is a separate decision from the Superset version
The Python runtime is a decision you make separately from the Superset version, because the interpreter constrains far more than the web application. Superset's Python version sets which packages can be installed, which database drivers you can load into the metadata database connection, and which Python the Celery worker and beat processes run under. Any custom code, visualization plugins or internal packages you have added to the image must also import cleanly on the target interpreter. Each of these can block the upgrade or be blocked by other work, so the runtime needs its own inventory before anyone schedules the Superset upgrade.
A team still running Python 3.9 or 3.10 may need to move the interpreter before the Superset upgrade can start. The Superset 5.0 notes deprecated Python 3.9 and recommended 3.11, and the notes after 6.1.0 remove 3.10 and require 3.11 or higher. Build a list of every package pinned in your requirements or image, including the metadata database driver for PostgreSQL or MySQL and any driver for your analytics databases, and confirm each one publishes a build for the target Python version. Do not assume a driver works on a new interpreter until you have installed it in a staging image and run a test query against each connected database. Confirm the exact minimum interpreter for your target release in its UPDATING notes before you commit to a date.
The web tier and the worker tier must run the same Superset release on the same Python version. Celery workers execute alert, report, async query and thumbnail tasks against the same code and configuration as the web application, so a mismatch can produce failures that appear only when a scheduled report runs. Treat the web and worker images as one artifact, rebuild both from the same base image, and roll them out together in staging. Record the interpreter version alongside the Superset version in your change log so that a rollback restores both.
How Python requirements affect PyPI installs, base images and drivers
A PyPI install takes its interpreter from the virtual environment you create, so the Python version is decided before pip runs. Confirm that the environment matches the Superset release you plan to install, and check the release notes for that line before you change anything. The apache-superset package page lists published versions and metadata, which helps you confirm the release you are pinning.
- Interpreter in the virtual environment: Create the environment with Python 3.11 or higher for 5.x and later upgrades, and record the exact minor version in your build notes.
- Pinned package version: Pin the package to the release you tested, because an unpinned upgrade can move a deployment onto a line that drops your interpreter.
- SQLite default: Quickstart and PyPI installs default to SQLite, which the architecture documentation does not recommend for production. Plan a PostgreSQL or MySQL metadata database and confirm the supported versions in the configuration docs.
- Commands from the same environment: Run every Superset command from the environment you validated, so the web service and workers use the same interpreter.
Before you promote a PyPI build, confirm the interpreter version, the pinned package version and the metadata database connection against the documentation for the release in use.
A container build carries Python inside its base image, so the image tag decides the runtime. Official images and custom builds both need the Python version confirmed against the release notes before a tag is promoted. Check the interpreter inside the built image, not only the tag name, because the tag and the contents can drift apart over time.
- Base image tag: Confirm the Python minor version in the tag itself, and pin the image by digest in your registry where your policy allows it.
- Custom Dockerfile: If you start from a Python base and install Superset with pip, that base must provide Python 3.11 or higher for 5.x and later upgrades.
- Build dependencies: Multi-stage builds that compile drivers need compilers and headers in the build stage for the same Python version as the runtime stage.
- Image changes between lines: Packaging changes between Superset lines can change what the official image contains, so read the Docker-related entries in UPDATING.md before you rebase a custom image.
- Compose databases: The Docker Compose PostgreSQL container is not recommended for production, so run the metadata database on a service you operate or manage separately.
Before you deploy an image, check the tag, the interpreter version reported inside the running container and the driver import tests.
Database drivers are a common cause of failed upgrades, because the web application can start while a connection library fails to load. Some drivers ship as prebuilt wheels only for certain Python versions, and others compile from source against system client libraries. Check each driver against the interpreter you chose, for the metadata database and for every warehouse connection the deployment uses.
- Wheel availability: For each driver, confirm that a wheel exists for your Python minor version and platform, or that your build toolchain can compile it reliably.
- System libraries: Compiled drivers often need client headers from the operating system, so list those packages in the image build and in the host baseline.
- Metadata database driver: The driver must match the PostgreSQL or MySQL line you run. The configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported metadata database versions.
- Import tests in staging: Import each driver under the new interpreter in staging before you run
superset db upgradeagainst a copy of production data. - Drift over time: Driver support for newer Python releases changes, so repeat the wheel check whenever you move to a later Superset line.
Record the driver name, version and wheel source for each connection, and confirm them against the release documentation and your own staging results before cutover.
What to prepare before changing the Python version
Changing the Python runtime touches every Superset process, not only the web tier. The cards below cover the inventory, backups, staging, rebuilds and rollback you need in place before the interpreter changes, following the upgrade guide's advice to back up, test in staging and check UPDATING.md.
Inventory interpreters on every host
Record the Python version on each web, Celery worker and Celery beat host, and on any image or virtual environment they run from. Mixed versions across these processes are a common source of confusing failures after a partial rollout. Confirm which hosts run which release of Superset, because the minimum Python version is tied to the release you are moving to. Check the output of the interpreter and the installed package list on each host, and write both down before you change anything.
Back up the metadata database
The upgrade guide asks you to back up the metadata database before running superset db upgrade and superset init. A runtime change is usually paired with a release upgrade, so the backup must be restorable to the exact state that the current interpreter can read. Test the restore on a separate instance, not only the dump file. Note the database engine version as well, since supported PostgreSQL and MySQL versions are listed in the configuration documentation.
Build a staging environment on the target Python
Create a staging Superset on the target Python version, using a copy of production configuration and a restored copy of the metadata database. Run the full set of dashboards, charts, alerts, reports and async queries against it, not just a login test. Staging is where you find packages that have no wheel for the new interpreter. Keep the staging result with the change record so the production window is based on tested behavior.
Rebuild custom plugins and drivers
List every database driver, custom visualization plugin, custom security manager and extra Python package in your environment. Each one must install and import on the target interpreter, and compiled drivers often need new wheels or build tools. Check UPDATING.md for changes that affect your build, and confirm each driver version with its vendor before you pin it. Rebuild the list into your container image or virtual environment so nothing depends on a manual install on a single host.
Confirm SECRET_KEY handling for restarts
Superset requires a user-specified SECRET_KEY to start. Before restarting web and worker processes on the new runtime, confirm that every process reads the same key and that the value is stored in your secrets system, not in a file that differs by host. If you rotate keys during the change, set PREVIOUS_SECRET_KEY so existing sessions and encrypted values stay readable during the transition. Test a login and a saved database connection after restart on staging.
Keep a rollback environment
Keep the current image, virtual environment or package set that runs on the existing interpreter until the new runtime has run through a full business cycle. Store the exact package versions and the configuration that matches them. If a migration or runtime fault appears, rolling back the code alone will not reverse database changes, so the rollback plan must name the database restore point as well. Confirm the rollback steps in staging before the production window opens.
How to move Superset to Python 3.11 without losing a rollback point
This sequence moves a running Superset onto a Python 3.11 runtime while keeping the current release, metadata database backup and runtime images available to roll back at each stage. Each step ends with a check that tells you whether to continue or stop.
Confirm the target release and its breaking changes
Identify the exact Superset release you plan to run and read the UPDATING.md notes for every version between your current release and the target. Confirm the Python minimum stated for that release, since the notes after 6.1.0 remove Python 3.10 support and require Python 3.11 or higher. Record the current Python, Superset, and database versions in a change ticket. The step is done when the owner signs off on the target version and the list of breaking changes that apply to your installation.
Back up the metadata database and current runtime
Take a full backup of the metadata database and confirm it can be restored into a scratch instance. For PyPI installs, save the virtual environment and the configuration file (superset_config.py) with its SECRET_KEY handling. For container and Kubernetes installs, record the image tag and digest currently deployed and keep it in the registry. The step is complete when a restore test succeeds and the previous image or environment is confirmed as still available. This is your primary rollback point.
Build a Python 3.11 staging environment
Create a staging environment on Python 3.11 with the same Superset release, configuration, and metadata database engine version as production. For PyPI installs, create a new virtual environment and install the pinned Superset version. For containers, build or pull the image for the target tag and confirm which Python interpreter it uses. Verify the interpreter with a version command inside the environment. The step is done when the staging Superset process starts and reports the expected Python and Superset versions.
Rebuild drivers and custom packages
Reinstall every database driver, custom visualization plugin dependency, authentication package and any other Python package that Superset loads. Packages with compiled extensions must be rebuilt or replaced with 3.11 wheels, so confirm availability for each one with its vendor or project. Keep a list of what was installed, with versions, so the set can be reproduced later. The step is complete when every package imports cleanly inside the 3.11 environment and each database connection in staging opens successfully.
Run database migrations and initialization in staging
Point the staging instance at a restored copy of the production metadata database, then run superset db upgrade followed by superset init. Capture the command output and any warnings, and note any migration that locks tables or runs for an extended time, since those affect the production window. The step is done when both commands finish without errors and the Superset web interface loads. Do not run these commands against production until staging results are accepted.
Test dashboards, charts, alerts and reports
Run a scripted test plan in staging covering dashboard rendering, chart queries against each connected database, SQL Lab execution, row level security, exports, and a sample of scheduled alerts and reports. Include async queries and dashboard thumbnails if your deployment uses the caching layer and worker components. Compare results with the production baseline and record every difference. The step is complete when the owner accepts the test results and any failures have a documented fix or a decision to defer them.
Roll the web tier, then workers and beat
Move production in a planned order: switch the web tier to the 3.11 runtime first, then the Celery worker tier, and the beat scheduler last, so only one scheduler is active at a time. Keep the previous image or environment running until each tier passes a health check and a sample query. Confirm with the team that alerts and reports still fire after the change. The step is done when all tiers run on Python 3.11 and the post-change checks pass. If a tier fails, return that tier to the previous runtime using the backup and image from the earlier steps.
Retain the rollback point until acceptance
Keep the pre-change metadata database backup, the previous runtime image or environment, and the staging test record until the business owners accept production. Confirm with your team how long these artifacts are retained under your own change policy, since no retention period is set by Superset itself. Close the change ticket with the final Python, Superset and driver versions. The step is complete when the acceptance record is filed and the rollback artifacts are tagged and linked to the change.
What makes a Python upgrade take longer
This table lists the factors that stretch a Python runtime change on Superset, with why each one matters and how to check it in your own environment. Use it to size the work before you agree a plan, since most of the effort sits in custom code, drivers and the migration rather than in the interpreter itself. The main takeaway is that a small, well-tested estate with a booked maintenance window moves far faster than a large one tested only by hand.
| Driver | Why it matters | How to check it |
|---|---|---|
| Custom Python packages and plugins | Every package installed alongside Superset must support the new interpreter and the Superset release, and custom visualization plugins may also need front-end changes. | List every package in your requirements file and image build, then confirm each one installs on Python 3.11 in a clean virtual environment. |
| Compiled database drivers | Drivers with C extensions, such as those for Oracle, SQL Server or ClickHouse, can lack prebuilt wheels for a new interpreter and force a local compile. | Run pip install for each driver on the target Python version and note whether it uses a prebuilt wheel or compiles from source. |
| Web, worker and beat hosts | Each host runs its own copy of the application, so every host must be moved and restarted in a controlled order if you run Celery workers and beat. | Count the hosts and containers per process type and record which ones share a virtual environment or image. |
| Metadata database size | The superset db upgrade step runs migrations against this database, and large tables can take longer and need a tested rollback. | Check row counts and table sizes for the metadata database, and time a migration on a restored copy. |
| Staging coverage of dashboards and reports | Without staging coverage, regressions in charts, scheduled reports and alerts surface only after users notice them. | Compare the dashboards, datasets, alerts and reports in production with those exercised in staging and list the gaps. |
| Maintenance window availability | Upgrades that restart web, worker and beat services need agreed downtime or a rolling plan, and scheduled reports must not fire mid-change. | Confirm with business owners which windows are open, which reports run on a schedule, and who approves the change. |
Questions teams ask before upgrading Superset's Python version
What does a Python version upgrade for Superset cost?
The cost is mostly labor, and no supplied fact gives a figure, so the reader should ask for a written quote built from their own scope. The main components are an environment assessment, rebuilding the runtime (virtual environment, PyPI install or base image), testing drivers and custom plugins, staging validation of dashboards and reports, and the cutover. Most of this is one-time work. Recurring costs appear only if the team keeps a custom image or plugins that must be rebuilt for each Superset release. Ask any provider to split the quote into one-time and recurring items and to list which drivers, plugins and images are included.
How long does a Python upgrade take?
Duration depends on how much the environment has been customized and how much data and content sits on the instance. A stock PyPI install with a few database connections is simpler than one with custom Docker images, private packages, custom visualization plugins and many scheduled reports. Dashboard and report testing usually takes the most time because every owner's content needs checking. Ask for a timeline that names the staging test scope, the number of connections and drivers to validate, and the dependencies on other upgrades such as a 6.x to 7.0 move.
What does the upgrade need from our team?
Plan for access and owners before the work starts. The team needs access to the Superset host or container build, the metadata database, the database credentials used by each connection, and a staging copy to test against. Dashboard, chart and report owners must confirm that their content still renders and sends correctly after the change. Someone with authority should approve the cutover window. Confirm these roles in the statement of work so that testing does not stall while owners are found.
Can our own team handle the Python upgrade alone?
Yes, if the team has Python packaging experience, can test a staging instance, and has owners ready to validate dashboards and reports. The work is most risky when drivers compile against system libraries, when custom images are built by hand, or when no staging copy exists. A partner is useful when the team lacks capacity or needs an independent test plan. Whichever route is chosen, the upgrade documentation calls for a metadata database backup, testing in staging first and checking UPDATING.md for breaking changes.
Can we stay on Python 3.10 after Superset 6.1.0?
No. The UPDATING notes that follow 6.1.0 remove Python 3.10 support and require Python 3.11 or higher. Teams that remain on 3.10 can keep running 6.1.0 for as long as it suits them, but they cannot take later releases on that runtime. Plan the interpreter change before moving to any release after 6.1.0, and confirm that every driver and custom plugin installs cleanly on 3.11.
What should we confirm about Superset 7.0 before planning?
Superset 7.0 is listed as a release candidate, and the supplied GitHub releases entry shows 7.0.0rc2 on October 16, 2026. Confirm the final release date, the minimum Python version in its UPDATING notes, and any changes to SQLAlchemy, screenshots or async queries before scheduling work. Ask the provider how they will adjust the plan if the final release differs from the release candidate. Treat the 6.x runtime and 7.0 changes as one planning exercise so that the team does not upgrade Python twice.
How do PyPI installs, base images and drivers change with Python 3.11?
Each install path needs its own check. A PyPI install needs a 3.11 interpreter and a fresh virtual environment, since packages built for 3.10 are not reused. A container build needs a base image that provides 3.11, and any custom Dockerfile must be rebuilt. Database drivers must be confirmed for the target Python version, because a driver that compiles only on older interpreters blocks the upgrade. Ask the provider for a driver matrix that lists each connection, its driver package and the tested interpreter version.
How DeployOpen scopes and delivers a Superset Python upgrade
DeployOpen plans and delivers Python runtime changes for self-hosted Apache Superset inside your own infrastructure, from the image and driver inventory through staged testing. Each engagement starts with a written, fixed scope so the Python target, deliverables and timeline are agreed before work begins.
How we scope
- Inventory the current Superset version, Python runtime, base image and installation method (PyPI, container or source)
- List every database driver, custom plugin and Python dependency that must import cleanly on the target runtime
- Confirm the target Superset release and its Python floor against the project's UPDATING notes before quoting
- Agree in writing which environments, dashboards, alerts and reports are in the test set and who signs off
How we build
- Build a new Python 3.11 or higher environment and image, pinning versions so rebuilds are reproducible
- Rebuild and retest drivers, the caching layer and Celery workers, since they run on the same runtime
- Run the superset db upgrade and superset init sequence in staging after a verified metadata database backup
- Test dashboards, SQL Lab queries, scheduled reports and thumbnails before any production change
How we hand over
- Deliver the tested image or install recipe, configuration files and a dependency lock with version records
- Document the rollback path to the previous runtime and the backup restore steps, tested before cutover
- Provide a test evidence pack covering staging results, driver checks and sign-off records for your change board
- Walk your platform and data teams through the new runtime, patch cadence and the upgrade checklist
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Track each future Superset release for Python floor changes and plan the next runtime move in advance
- Re-test drivers and custom plugins whenever the base image or Python patch level changes
- Review the self-hosted deployment's dependencies and runtime versions on a schedule agreed in the retainer
