Why Superset Docker image changes matter when upgrading
Image changes can break a custom Superset build even when your application code and dashboards are unchanged. If your team runs a custom image built on the official base and must move to a newer 5.x or 6.x release, the supported approach is to read the breaking change notes in the project's UPDATING.md file and test your image build before cutover. The official base images changed in ways that matter for custom builds: Superset 5.0 switched Python package installs in the Docker images to uv pip install, and translations stopped being built by default unless BUILD_TRANSLATIONS=true is set. Your bootstrap scripts, driver installs and build arguments need to be checked against those changes, not only the Superset code.
The upgrade path in the Superset upgrade documentation applies here as well: back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes between versions. Treat the image build as one more artifact in that sequence. Rebuild it from the target tag in a staging environment, confirm that every driver your analysts depend on still installs and imports, and confirm that the running container starts with your superset_config.py and secret key handling intact. Confirm the exact target tag and its image variant with your own registry and the project's Docker builds, images and tags documentation, because tag names and defaults have changed between releases.
Plan this work before the upgrade window opens. Superset 6.1.0 was published on PyPI on May 13, 2026, and later UPDATING notes changed the default apache/superset image so it is batteries-included, with the minimal image moved to -lean tags. A build pinned to an older lean-by-default assumption can therefore pull in a different set of packages, or lose one, after a tag change. Decide which image variant you will build from, record that choice in your build pipeline, and ask your team to confirm each driver, browser dependency and translation requirement against the release you are targeting.
Which image changes affect custom builds
This table lists the official Superset image changes that can break a custom build, with the impact on each and the action to take before upgrading. Read each row against your Dockerfile and bootstrap scripts, since the same change can be harmless for one team and breaking for another. The main takeaway is that anything that installs drivers, translations or browser tooling at build time needs to be checked explicitly.
| Change | Impact | Action needed |
|---|---|---|
| uv pip install in 5.0 | Bootstrap scripts that add drivers with pip may fail or install into an unexpected environment | Rewrite driver installs to use uv pip install and test the image build from a clean cache |
| Translations off by default in 5.0 | Non-English interface strings are missing unless the build enables them | Set BUILD_TRANSLATIONS=true at build time if your users need translated interfaces |
| INCLUDE_CHROMIUM false by default in 6.0.0 | Custom builds that relied on Chromium in the lean layer lose screenshot support for reports and thumbnails | Set INCLUDE_CHROMIUM explicitly, or add Chromium in your own layer, and test report output |
| Batteries-included default image after 6.1.0 | The default tag adds PostgreSQL and MySQL drivers, MCP dependencies and Playwright Chromium, so image size and contents change | Compare the new default image contents with your current build and remove or pin anything you no longer need |
| Minimal image moves to -lean tags | Pipelines that pull the minimal image by its old tag may get the larger default image or a missing tag | Update image references to the -lean tag where you want the minimal image, and confirm tag names in the Docker builds documentation |
| Full list of breaking changes | Other changes between releases are not covered in this table | Read the breaking change notes in UPDATING.md for every version between your current and target release |
How the image build changed from 5.0 to the batteries-included default
The official Superset image is assembled in layers, and a few build arguments decide what goes into them. Starting with 5.0, Python packages in the image are installed with uv pip install rather than the pip flow older custom bootstrap scripts may expect, so a RUN step that adds a database driver to an extended image can fail or land in a different site-packages path. Translations also stopped being built by default in 5.0 and now require BUILD_TRANSLATIONS=true. In 6.0.0 the Dockerfile default for INCLUDE_CHROMIUM changed to "false", so the Chromium layer is lean by default. Each of these changes is recorded in the project's Docker builds, images and tags documentation and the UPDATING notes. Confirm which build arguments your current image was built with before assuming any of them still apply.
A Dockerfile that starts with FROM apache/superset inherits whatever the base layer contains at build time, so a tag change can alter the result without any edit to your own file. Your bootstrap logic may assume a driver is already present, that a Chromium binary exists for alerts and reports, or that translation files ship with the image. If one of those assumptions was true on the old tag and false on the new one, the build can still succeed while reports or drivers quietly break at runtime. The fix is to test the rebuilt image, not only the build log: check that each driver imports, that a report renders a screenshot, and that the UI loads the locale you need.
The batteries-included default is the most important change to review. After 6.1.0, the default apache/superset tag includes PostgreSQL and MySQL drivers, MCP dependencies and Playwright Chromium, while the minimal build moves to -lean tags. A team pinned to a tag name that has no suffix may therefore receive a larger image with different packages on the next pull, and a team that moves to -lean must add back any driver or browser dependency it relied on. Ask your platform owner to record the exact tag and digest in use, compare the installed package list between the two images, and decide per dependency whether it belongs in the base image, a derived image or nowhere. Confirm the current tag names against the release notes before you change any pin.
What changes depend on how you build
Teams that add database drivers or other Python packages through a Dockerfile layer or bootstrap script on top of the official image feel the change first. Since 5.0, the images install Python packages with uv pip install, so a script that calls pip directly or assumes a particular environment layout can fail or install packages into the wrong place.
- Installer command: Replace
pipcalls in custom layers withuv pip installand confirm the target environment matches the one Superset runs in. - Driver packages: Check that every database driver you add, including drivers for your analytics connections, resolves under uv and loads at startup.
- Translations: Since 5.0, translations are not built by default. A layer that expects compiled locale files will show untranslated text unless you set
BUILD_TRANSLATIONS=true. - Chromium assumptions: From 6.0, the lean layer leaves Chromium out by default, so scripts that expect a browser binary will fail during report or thumbnail steps.
Build the image, start the stack, connect each driver, run a test query and trigger a screenshot on staging. Confirm each change against the UPDATING.md notes for every release between your current version and your target.
Teams that rebuild the image from source use build arguments to decide what it contains. In 6.0, the Dockerfile default changed to INCLUDE_CHROMIUM="false", and translations are built only when BUILD_TRANSLATIONS is set to true. A pipeline that never passes these arguments will produce a different image after an upgrade than it did before, even though the pipeline itself has not changed.
- INCLUDE_CHROMIUM: Pass it explicitly. Set it to
truewhen alerts, reports or thumbnails need the browser, and record that choice in the pipeline. - BUILD_TRANSLATIONS: Set it to
trueif your users need translated interface text, because the default no longer builds it. - Pinned versions: Pin the Superset version in the build so a rebuild after an upgrade does not pick up a new default without review.
- Build records: Store the arguments and the resulting image digest with each release so operators and auditors can trace what was installed.
Compare installed packages and feature behavior between the old and new builds, and run a report on staging to confirm Chromium is present when you expect it. Confirm the exact argument names and accepted values for your target version in the Docker builds, images and tags documentation before you change the pipeline.
After 6.1.0, the default apache/superset image is batteries-included. It ships PostgreSQL and MySQL drivers, MCP dependencies and Playwright Chromium. Teams that pull the default image unchanged gain components they may not have reviewed. The most likely break is not a failed build but a larger image with more packages to scan, a browser that your security baseline may not allow, and behavior that changes on the next pull if the tag is not pinned.
- Bundled drivers: PostgreSQL and MySQL drivers come preinstalled. Confirm that your connection list matches what the image provides and that no other driver is expected from it.
- MCP dependencies: Review the added dependencies in your software bill of materials and your vulnerability scanner output.
- Playwright Chromium: The browser is present, so reports and thumbnails work without a build step. It also adds to the attack surface and to the resources each worker uses.
- Unpinned tags: A pull can change behavior without any change to your Dockerfile. Pin the version tag in your deployment manifests.
Scan the image, compare its contents with the image you run today and run a report on staging. Confirm the included components and tag behavior in the Docker builds documentation and the UPDATING notes for the release you plan to pin.
The minimal image moves to -lean tags after 6.1.0. Teams that want a smaller footprint pull those tags and add what they need. A lean image keeps the footprint small, but it returns the work of adding drivers and the browser to your team. The lean image is correct only when every feature your users depend on has its dependency in place, so the decision starts with a list of features rather than with the tag itself.
- Metadata database driver: The default image ships PostgreSQL and MySQL drivers. Confirm whether the lean tag includes them, and add any missing driver in a layer before first boot.
- Analytics connections: Each warehouse or query engine that your users connect to needs its driver available in the running image.
- Browser features: Alerts, reports and thumbnails need Chromium. Decide whether to add it in a layer or to keep those features off in the lean deployment.
- Tag names: Confirm the exact
-leantag for the version you pin before you write the pipeline, since tag naming changed with this move.
Build a feature checklist, then run each feature on staging, including a metadata database connection on first boot. Confirm the lean tag contents and naming in the Docker builds, images and tags documentation before you adopt them.
What to prepare before changing the image
Image changes break builds quietly, so the preparation is mostly inventory and rehearsal. The six items below build on each other: you need to know what your image adds before you can rebuild it, and you need a rollback point before you touch the metadata database.
Inventory custom Dockerfiles and bootstrap scripts
List every Dockerfile that extends the official Superset image, along with any entrypoint or bootstrap script that runs at container start. Note which base tag each one pulls. The 5.0 change to uv pip install matters most for scripts that call pip directly or assume a specific package layout, so flag those first. Ask your team who owns each file and whether it is still in version control.
List drivers and packages added at runtime
Record every database driver, Python package and extra installed during the image build or at container start, including anything fetched by a startup command. Packages installed at start time are the easiest to miss and the hardest to reproduce. After 6.1.0 the default image ships PostgreSQL and MySQL drivers, so check which of those you still install yourself to avoid duplicate or conflicting versions.
Back up the metadata database first
Take a verified backup of the Superset metadata database before the new image runs any migration. The upgrade guidance calls for this step before superset db upgrade and superset init. Confirm you can restore the backup into a scratch instance, not only that the backup file exists. Store the backup outside the Superset host so a failed container rebuild cannot remove it.
Mirror production images in staging
Build a staging environment that runs the same image tag, base layers, drivers and configuration as production, with only the hostnames and secrets changed. A staging instance on a different image than production tests the wrong artifact. Include the same metadata database engine and version, since migration behavior differs between engines. Ask the team to confirm that staging was built from the same Dockerfile revision you will deploy.
Test dashboards, connections and reports
Write a test list that covers the three areas most likely to break after an image change: dashboards that render charts from each connected database, database connections that authenticate and return results, and scheduled alerts and reports that generate screenshots. Reports depend on the browser layer, so confirm they produce output after the Chromium change. Record pass or fail for each item before and after the change.
Record the image digest for rollback
Before deploying, record the exact image digest currently running in production, not only the tag, because tags such as latest can point to different builds over time. Keep the Dockerfile revision and the metadata database backup paired with that digest. If the new image fails, you can redeploy the recorded digest, but a rollback after a successful migration may also require restoring the database backup, so decide that path in advance.
How to sequence the image upgrade
This sequence moves a custom Superset image from the old base to the new one in a controlled order, so every build change is checked in staging before the tagged image is promoted and the previous image remains available for rollback.
Read UPDATING.md for every release in between
The team owning the Superset image reads the breaking change notes in the project's UPDATING.md for each release between the current version and the target, not just the final one. Image-related notes such as the uv pip install switch in 5.0, the Chromium default change in 6.0 and the batteries-included default after 6.1.0 are recorded in a short change list for this build. Done when every intervening release has been reviewed and each image-affecting note appears on the list with its owner.
Rebuild the custom image from the new base
In a branch, the team rebuilds the custom image on top of the new official base instead of editing the old Dockerfile in place. Custom bootstrap scripts, added drivers, translation files and any extra layers are carried over deliberately, and each one is noted as kept, changed or removed. Done when the branch builds cleanly from a clean cache and the build log shows every layer completing without manual steps.
Confirm driver installs succeed under uv pip install
Because Superset 5.0 images install Python packages with uv pip install, the team checks that every database driver and extra library in the custom bootstrap script installs under that tool, including pinned versions and any packages with native build requirements. The engineer runs each driver import inside the built image and records the result. Done when every driver the warehouses need imports successfully and the install log has no fallback or warning that changes the resolved versions.
Set BUILD_TRANSLATIONS and INCLUDE_CHROMIUM explicitly
The team sets BUILD_TRANSLATIONS and INCLUDE_CHROMIUM in the build configuration rather than relying on defaults, since translations stopped building by default in 5.0, the lean layer default changed in 6.0, and the default image became batteries-included after 6.1.0. The chosen values are written into the build definition with a comment on why. Done when a rebuild with the same inputs produces the same set of components, and the team can point to the flags in the build file and the image contents that match them.
Run database upgrade and init in staging
Against a copy of the production metadata database, the team runs superset db upgrade and superset init from the new image, following the project's upgrade guide. The metadata database is backed up before this step and the backup location is recorded. Done when both commands finish without errors, the migration log is saved, and the staging instance starts and serves its login page.
Test dashboards, reports and thumbnails
Testers open a representative set of dashboards, run the charts that depend on custom drivers, and trigger a test alert or report so the worker and screenshot path is exercised. Thumbnails and any Chromium-dependent screenshots are checked on the new image, since the browser layer may differ between the full and lean tags. Done when the agreed test list passes, each failure is logged with its root cause, and the test owner signs off in writing.
Promote the tagged image
Once staging passes, the team tags the verified image with a version-specific tag that matches the build record, then points production to that tag rather than a floating tag such as latest. The promotion is recorded with the image digest, the build commit and the staging test sign-off. Done when production pulls the exact digest recorded in the release note and the running containers report the expected Superset version.
Keep the previous image as the rollback point
The previous production image and its tag are retained in the registry, and the metadata database backup taken before the upgrade is kept with it. Rollback is confirmed in advance by checking the team can redeploy the old image and restore the backup, noting that the schema may not be reversible by simply swapping images. Done when the rollback procedure is written down, the old digest is verified as still pullable, and the restore has been checked against the backup in a non-production environment.
What makes an image upgrade take longer
This table lists the factors that change how much work a Superset image upgrade involves, and how each one affects the work. Read it before requesting a quote, because each driver should appear as a line item or an explicit assumption in the written scope. The main takeaway is that the number of custom layers, install-time scripts and migration test data usually matter more than the version gap alone.
| Driver | Effect on the work | What to ask for in a quote |
|---|---|---|
| Number of custom Dockerfile layers | Each layer built on the official image must be rebased, rebuilt and retested against the new base, and layers that assume an older Python or package set break first | A list of every custom layer, the base image tag each one uses, and the rebuild and test steps included in scope |
| Bootstrap scripts that install drivers at start | Scripts that call pip or other installers at container start may fail under uv pip install, so each driver must be checked for compatibility and install behavior | Confirmation that every driver install path is inventoried and tested on the target image, including database drivers |
| Use of Chromium for reports and thumbnails | Lean images exclude Chromium from 6.0, and the default image changed after 6.1.0, so report and thumbnail rendering needs an explicit image choice and a test run | Which image tag the scope targets, whether screenshot output is verified, and who owns the rendering test |
| Translation builds | Translations are not built by default from 5.0 unless BUILD_TRANSLATIONS is set to true, so non-English interfaces need a build decision and a check | Whether translated interfaces are in scope and which build argument will be set and verified |
| Number of releases crossed | Each release between the current and target version may add breaking changes listed in UPDATING.md, so the review and test effort grows with the gap | A written review of each breaking change in the crossed releases and the mapping to your customizations |
| Size of the metadata database for migration testing | Migrations run against a copy of production metadata, and larger databases need more time to restore, migrate and verify, so test runs take longer | The database engine and version, approximate size, and whether a restored copy for staging is included or provided by the client |
Questions teams ask before changing their Superset image
Does moving to a newer Superset image always require a full rebuild of our custom image?
Usually yes, if your image adds drivers, plugins, translations or bootstrap scripts on top of the official build. The changes that matter most are the switch to uv pip install in the 5.0 images, the default of INCLUDE_CHROMIUM="false" in 6.0, translations no longer built unless BUILD_TRANSLATIONS=true, and the batteries-included default image with -lean tags after 6.1.0. Your Dockerfile and bootstrap scripts need to be checked against each change, because a layer that worked on an older base can fail silently or be redundant. Start from the UPDATING notes for every release between your current version and the target.
What drives the cost and effort of an image change?
The main driver is how much your image deviates from the official build. Cost rises with the number of custom drivers, bootstrap scripts, translation files, Chromium dependencies and plugins, and with how many environments you must rebuild and retest. Other factors are how many Superset releases you cross, whether your metadata database migration is also part of the upgrade, and how much reporting depends on screenshots. The cost components are internal staff time, any partner time under a written fixed scope, and recurring image rebuilds when new Superset releases arrive. Ask any quote to itemize the image audit, rebuild, staging test and cutover separately.
What does our internal team need to provide for this work?
Your team needs to supply the current Dockerfile, any custom bootstrap or entrypoint scripts, the list of drivers and plugins in use, and your registry and deployment pipeline details. It also needs an owner who can approve the staging test plan and decide which dashboards, alerts and reports are business critical. Access to a staging environment that mirrors production networking and database connections is needed before any cutover. Confirm with your platform team who can push images to your registry and who signs off on production changes.
Can our own team make these image changes without outside help?
Yes, if your team already builds and deploys containers and can read the release notes carefully. The work is well bounded: audit the custom layers, adjust them for the changed install tool, translation build flag and Chromium default, rebuild, and test. Teams with no container pipeline, or those who must also migrate the metadata database, often choose a fixed-scope partner for the image work. Whichever path you choose, put the decision and the owner in writing before the upgrade window opens.
How does a -lean image tag affect scheduled reports and screenshots?
Scheduled reports and thumbnails depend on Chromium. The default image after 6.1.0 includes Playwright Chromium, but a -lean tag does not, so an image deployed from a lean tag without a Chromium layer can fail to produce report screenshots. Before choosing a lean tag, list every alert, report and thumbnail feature you use and confirm that the chosen image includes the browser they need. If you run a lean base, add Chromium deliberately in a layer you control and test it. Confirm the exact package and layer details against the Docker builds and tags documentation.
What should we test before switching production to the new image?
Test the things the image change can break, not only whether the web page loads. Check that every database driver your connections use still imports and connects, that custom plugins and translations render as expected, and that Celery workers and beat can reach Redis and the metadata database. Run a sample of dashboards, scheduled reports and alerts, and confirm that the screenshots they produce are correct. Check logs for warnings from the new install step. Keep the test evidence with the change record so auditors and operators can see what was verified.
How does rollback work if the new image fails in production?
Rollback is straightforward for the container itself if you keep the previous image tag in your registry and your deployment can redeploy it. It is not enough on its own when the release also ran database migrations. Back up the metadata database before the change, and confirm whether the target release's superset db upgrade and superset init steps can be reversed for your version. The upgrade documentation covers the backup and migration order. Document the rollback steps and test them in staging before the production window.
What a DeployOpen image upgrade covers
A fixed-scope image upgrade starts with a written review of your current build against the breaking change notes in the project's UPDATING.md. The review inventories every place your images depend on the official Superset image: custom bootstrap scripts that add database drivers, Dockerfile layers that install Python packages, translation files, and any screenshot or report path that expects Chromium to be present. Each finding is recorded with the release that changed the behavior, the file or layer affected, and the fix proposed. The scope also states which target tag you will run, such as a batteries-included default image or a -lean tag, because that choice changes which layers you still need to add yourself. Scope, deliverables and timelines are agreed in writing before work starts, and the review output becomes the list both parties sign off on.
The build phase produces rebuilt custom images from your Dockerfiles and bootstrap scripts, pinned to the base tag you approved, with the drivers, translations and browser dependencies your environment needs stated explicitly. Testing covers the image itself (startup, driver import, superset db upgrade and superset init against a copy of your metadata database) and the running application in a staging environment that mirrors your production configuration, including the SECRET_KEY handling, the metadata database engine, and the worker and caching components if you use alerts, reports or thumbnails. Staging validation requires access to a staging environment that matches production closely enough to be meaningful, a metadata database copy, and test accounts that represent each role you rely on. Confirm these access arrangements early, because they usually determine the timeline more than the image changes do.
Cutover and rollback records are the deliverables most often missing from in-house upgrades. The engagement should produce a cutover runbook with the image digests deployed, the order of migrations and restarts, the checks performed after each step, and a dated record of the results. The rollback section names the previous image and the metadata database backup to restore, and states who has authority to trigger it. Ask any prospective partner to show a sample runbook and to explain who in your organization must approve the production change, what evidence they hand over at the end, and which items are their responsibility after handover versus yours. Support or retainer work for later image changes is priced separately from this one-time scope.
How DeployOpen scopes and delivers Superset image upgrades
DeployOpen treats Superset Docker image changes as a bounded piece of upgrade work inside your own infrastructure. We start from your current custom image, check it against the image changes in the project's breaking change notes, and deliver a tested build with documentation your team can run.
How we scope
- The written scope lists every custom image layer, bootstrap script and driver your build adds today.
- We map each layer against the uv pip install, translation and Chromium changes and record which ones apply.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- Quotes follow from the written scope, so ask which image tags and target versions the quote covers.
How we build
- We rebuild the custom image on the official base for your target release, using the tag you choose.
- Driver installs are reworked for the uv-based package step and checked against your database connections.
- Translation builds and Chromium inclusion are set explicitly, so the image no longer depends on defaults.
- Build output is tested in a staging environment with dashboards, alerts and reports exercised before cutover.
How we hand over
- You receive the Dockerfile, build arguments, bootstrap scripts and a pinned image tag reference.
- The documentation records each image change, the decision taken and the test evidence behind it.
- We walk your platform team through a rebuild and rollback run so they can repeat it without us.
- Your team keeps the build source in your own repositories and registries, under your control.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer for future image releases.
- A retainer can cover re-testing the custom image when a new tag or base image is published.
- Ask whether support includes staging test runs for dashboards and reports after each image rebuild.
- Confirm response expectations and the change process in the written agreement before work begins.
