Why THEME_OVERRIDES stops working after the 6.0 upgrade
If your Superset instance carries custom branding, the THEME_OVERRIDES setting no longer drives it once you move to 6.0, and the branding has to be rebuilt on the 6.0 theming system before the upgrade reaches production. Branding that changes the browser title or uses custom fonts needs a second pass on the 6.1 line, because two more settings change there. Plan the work as two steps on one supported path: 5.x to 6.x, then 6.x to 6.1, with testing after each step rather than one combined cutover.
The theming change lands in 6.0, where Superset replaced THEME_OVERRIDES with a theming system based on Ant Design 5. Any color, typography or component values you set through the old setting need to be translated into theme tokens and checked on the 6.0 build. The title and font changes land in 6.1: APP_NAME no longer controls the browser title or frontend branding, which moves to the brandAppName theme token, and CUSTOM_FONT_URLS was removed in favor of a per-theme fontUrls token. An instance that only sets APP_NAME for a title will show the default title after 6.1 until the token is in place, so confirm this on a staging copy.
The upgrade guide and the project's UPDATING.md are the authority for breaking changes between versions, so read the entries for every release between your current version and your target before you write any configuration. Confirm the exact wording of each entry against the release you will deploy, because the notes can change between release candidates. Your branding inventory should record each setting you override, the release where it breaks, and the owner who will sign off the visual result.
Which branding settings change, and what to do about each
This table lists each branding setting that changed across the 6.0 and 6.1 releases, what the change affects in a running Superset, and the work your team should plan. Read it as a checklist: find every legacy setting in your configuration and custom assets, then confirm the replacement before your staging test.
| Change | Impact | Action needed |
|---|---|---|
| THEME_OVERRIDES replaced in 6.0 | Overrides in your config no longer style the UI. The 6.0 theming system is built on Ant Design 5 theme tokens. | Find every THEME_OVERRIDES entry, map each value to an Ant Design 5 token, and review the 6.0 UPDATING notes for the full list of changes. |
| APP_NAME stops controlling branding in 6.1 | The browser title and frontend branding no longer follow APP_NAME. Those now come from the brandAppName theme token. | Set brandAppName in your theme, keep APP_NAME only where your version still reads it, and confirm the browser tab title in staging. |
| CUSTOM_FONT_URLS removed in 6.1 | Custom font files loaded through this setting stop loading, so text falls back to default fonts. | Move font sources into the per-theme fontUrls token and verify that each theme loads its fonts in staging. |
| Per-theme fonts and theme scope | Fonts and tokens now belong to a theme. A setting applied globally in the old model may need to be defined in each theme you use. | List every theme in use, define tokens and fontUrls for each, and test users who switch themes or use embedded dashboards. |
| Custom CSS that targets Ant Design internals | Selectors that relied on the Ant Design version bundled with the old release may no longer match elements or spacing. | Audit custom CSS and chart overrides against the new Ant Design 5 markup, then follow the plugin upgrade page for chart code changes. |
| Custom chart plugins using Ant Design components | Plugins that import or style Ant Design components may render differently or fail after the theming change. | Test each custom plugin in a staging build and confirm the upgrade steps before promoting the release. |
| Logos, favicons and static assets | Branding files referenced from configuration may be unaffected by the token change but still need a check after the upgrade. | Confirm asset paths, sizes and cache behavior on every page users see, including login and error pages. |
| Dashboards and charts under the new theme | Colors, fonts and layout of existing dashboards can shift, which affects exported images and reports. | Compare key dashboards and scheduled report output before and after the change, and record any visual differences for sign-off. |
How the theme token model differs from THEME_OVERRIDES
The old THEME_OVERRIDES setting was a dictionary of values that Superset merged into its styling, so a single block could carry colors, fonts and branding together. Superset 6.0 replaced that approach with a theming system built on Ant Design 5, where appearance is set through named theme tokens that belong to a theme. Each token has a name and a supported value type, and the value applies to the component family that reads it. The practical change is that you no longer write free-form keys and hope the frontend picks them up. You map each intended look to a token name that the target release documents, and you set it per theme. Before you touch configuration, confirm the exact token names and accepted values in the 6.0 and 6.1 documentation and the UPDATING notes for the version you are moving to, because names and behavior have changed between releases.
Start with an inventory of what the current configuration actually does. Record every color value, the logo file and its sizes, each font and its source, the application title, and any custom CSS blocks. Then sort each item into one of three buckets. Colors and typography usually map to tokens. Logos and favicons are image assets that you place and reference through the configuration the target version documents, so they need a file list and a location, not a token value. Custom CSS is the riskiest bucket: rules that targeted old class names or generated markup may not match the Ant Design 5 output, so mark each rule as kept, replaced by a token, or retired. Titles are a special case in 6.1, where the browser title and frontend branding moved to the brandAppName token and APP_NAME no longer controls them, so check every place the old title is set.
Fonts need their own decision. In 6.1, CUSTOM_FONT_URLS was removed in favor of a per-theme fontUrls token, so each theme now carries its own font sources. Confirm whether your fonts are self-hosted or loaded from an external host, since that affects both licensing and the restricted network rules in your security baseline. Ask who owns each brand asset and who approves changes, because a theme is now a versioned artifact in your deployment rather than a single settings block. Plan a test pass for every theme against a representative dashboard, a chart with a legend, a modal and an error state, since token changes can alter contrast and readability in ways the old overrides did not.
What to prepare before changing any branding setting
Branding changes in Superset touch configuration, the frontend build and every dashboard a user opens, so the work starts before anyone edits a theme. The cards below cover what to inventory, where to rehearse, what to back up and who must approve the assets before the migration begins.
Inventory current branding settings
List every current THEME_OVERRIDES value, the APP_NAME setting, any CUSTOM_FONT_URLS entries and each custom asset such as logos, favicons and font files. Record where each one is set, whether in superset_config.py or environment variables, so nothing is missed during the move. Note which values are still used on the running version, because some settings only take effect after an upgrade.
Build a staging copy
Create a staging environment with a copy of the production metadata database and configuration files. Use it to rehearse the theme change before any production change window. Ask the team to confirm that staging loads the same custom assets and reverse proxy paths as production, since a theme that works in a test environment can still fail behind production routing.
Back up before any migration
Take a verified backup of the metadata database and the configuration files before running any upgrade or migration command. Keep the backup outside the host that runs Superset so a failed change can be reversed. Confirm the restore procedure with a test restore on staging, because a backup that has never been restored is not yet proof of recovery.
Capture a visual reference set
Screenshot a fixed set of dashboards, charts and scheduled reports in their current branded state, including light and dark views where users use them. Choose pages that show the header, title, fonts and colors, and record the browser and screen size. The set becomes the baseline for comparing the new theme tokens and catching regressions in dashboards and report output.
Confirm brand and font ownership
Get written sign-off from the people who own the logo, color palette and fonts before the new theme is built. Confirm that the font files are licensed for web serving from your own infrastructure, since a font served from a CDN may carry different terms. Record who approved each asset and its version so the sign-off can be checked during a later audit.
Match staging to production builds
Run staging on the same Superset release, Python version, container image and frontend build as production. Theme tokens are compiled into the frontend, so a different image or build can produce different output. Confirm the exact image tag or package version on both environments before comparing screenshots, so that differences are caused by the theme rather than the platform.
Sequence for rebuilding the theme and testing it
This sequence moves Superset branding from THEME_OVERRIDES onto the 6.0 theming system in staging first, then checks each surface users see before production changes. Each step ends with a check and a rollback point, so the team can stop or reverse at any stage.
Capture current branding and baseline screenshots
The platform owner and a frontend-aware engineer record the current THEME_OVERRIDES block, APP_NAME, CUSTOM_FONT_URLS, logo files and font files from the production configuration. They also capture screenshots of the login page, a home page, a representative dashboard, a chart with its tooltip and an alert or report thumbnail, so later differences are easy to see. The step is done when the settings are stored in version control and the baseline screenshots are filed with the release ticket. Rollback at this stage is not needed because nothing has changed, but the captured settings become the reference for restoring the old look if the new theme is abandoned.
Back up the metadata database and configuration
The platform owner takes a verified backup of the metadata database and a copy of superset_config.py and any mounted theme or font assets. The team restores the backup into a scratch instance to confirm it is readable before relying on it. The step is complete when a restore test succeeds and the backup location, timestamp and checksum are recorded. Rollback point: this backup is the state you return to if a migration or theme change must be reversed, so it must be kept until the production change is closed.
Upgrade staging to the target 6.x release
The platform engineer upgrades a staging copy of the deployment to the target 6.x release using the upgrade guide, running superset db upgrade and superset init in that order and checking UPDATING.md for every breaking change between the current and target versions. The engineer confirms the web and worker processes start cleanly and that the SECRET_KEY is still set. The step is done when the staging instance loads and the migration log shows no errors. Rollback: restore the staging metadata database from the backup and redeploy the previous image, then repeat the upgrade after the cause is fixed.
Remove THEME_OVERRIDES and map settings to tokens
A frontend engineer removes the THEME_OVERRIDES block, which no longer applies in 6.0, and translates each value to a theme token in the Ant Design 5 based theme definition, such as primary colors, font family and border radius. Settings with no direct token are listed for a design decision rather than guessed. The step produces a theme file in version control and a short mapping table from old keys to new tokens. It is done when the staging instance renders with the new theme and the mapping table has no unresolved entries. Rollback: restore the previous configuration file from version control and restart the web processes.
Set brandAppName and per-theme fontUrls
For 6.1 and later, the engineer sets the brandAppName token, because APP_NAME no longer controls the browser title or frontend branding, and replaces CUSTOM_FONT_URLS with the fontUrls token inside each theme definition. The team confirms that the font files are reachable from the browser on the network path users actually use, including any internal CDN or proxy rules. The step is done when the browser title shows the new name on the login page and the fonts load without console errors. If the target release is 6.0 only, confirm which of these settings it supports before setting them. Rollback: revert the theme file to the mapping-table version and remove the font entries.
Rebuild assets and restart web and worker processes
The platform engineer rebuilds the frontend assets so the new theme is compiled, then restarts the web servers and the Celery worker and beat processes together, since the worker generates alert, report and thumbnail images that also carry branding. The engineer clears any cached assets in the reverse proxy or CDN before the restart is considered complete. The step is done when all processes report healthy and a new page load shows the new theme on every node. Rollback: redeploy the previous build artifacts and restart the same set of processes.
Verify login, dashboards, charts, alerts and thumbnails
A tester with a non-administrator role compares the staging screens against the baseline screenshots from the first step. The test covers the login page and any SSO button, a dashboard with native filters, a chart with a tooltip and legend, an export, an alert or scheduled report email, and the dashboard thumbnail shown in the list view. The tester records each difference and classifies it as expected branding or a defect. The step is done when every surface is signed off in writing by the platform owner and the business owner of the dashboards. Rollback: if a defect blocks sign-off, return staging to the backup state and fix the theme file before repeating this step.
Promote to production with a defined rollback point
The platform owner schedules the production change, takes a fresh metadata database backup immediately before the upgrade, and applies the same steps that succeeded in staging using the same versioned theme file. The team confirms the rollback point is named in the change record, including the backup identifier, previous image tag and configuration commit. The step is done when the production smoke checks from the verification step pass and the change record is closed with the screenshots attached. If checks fail, the team restores the pre-change backup, redeploys the previous image and reverts the configuration commit, then reviews the failure before any retry.
How to test dashboards and reports after the theme change
Treat the theme change as a visual regression project. Before you cut over, capture reference screenshots of the pages your users depend on, then compare the rebuilt theme against them page by page. Cover the login page, home page, a representative dashboard, chart explore and SQL Lab in both light and dark modes if your organization uses both. For each page, check the browser tab title (which now comes from the brandAppName theme token on 6.1 and later), the logo in the header and login screen, the font families and weights loaded through the per-theme fontUrls token, and the primary, link and background colors. Include any embedded or public dashboards you expose, because they run under their own pages and browser settings and can look different from the main application even when the theme is correct.
Next, test the parts of Superset that render outside the normal browser view. Alerts, reports and dashboard thumbnails are generated by the worker and caching layer described in the architecture documentation, so a branding fix that looks correct in your browser can still produce stale or unbranded images in scheduled output. Trigger a test report and a test alert to a mailbox you control, open the attached screenshots, and confirm the title, logo, fonts and colors match your reference. Check that thumbnails refresh after you change the theme, since cached images may keep the old look until they expire or are cleared. Confirm the worker containers received the same configuration as the web containers, because a mismatch here is a common cause of partial branding. Also check any custom chart plugins, since their styles may hard-code colors or fonts that no longer match the theme tokens.
Repeat this full checklist after every Superset upgrade, not only after the theme change, because token names, default styles and component libraries can shift between releases. Check the UPDATING.md notes for the target version before each run so you know which theme settings were renamed or removed. Store the reference screenshots and the checklist in version control next to your theme configuration, and record who approved each set of results. Confirm with your own security and communications teams which pages and emails need to carry the approved branding, since those decisions determine the scope of the test plan.
What makes a theme migration take longer
This table compares the factors that expand or shrink a THEME_OVERRIDES migration and shows which way each one moves the effort. Read it before estimating, since the largest drivers are usually the number of dashboards to re-verify and whether a staging environment exists. Most teams find that the volume of custom CSS and per-theme variants decides how much rework the new token model requires.
| Driver | Effect on effort | What to check |
|---|---|---|
| Custom CSS files and overrides | More files and selectors raise effort, since each override must be mapped to a token or retired | Count every stylesheet and injected override, and note which ones target Ant Design component classes |
| Per-theme variants | Each extra theme repeats token, font and logo decisions and multiplies testing | List every theme in use and whether they differ only in colors or also in fonts and assets |
| Custom fonts and licensing | Font files must be re-referenced through fontUrls, and licensing may limit hosting choices | Confirm each font's license allows self-hosting and that the URLs resolve from every browser audience |
| Custom visualization plugins | Plugins that read theme values or hard-code colors need changes and their own test pass | Identify plugins that consume theme colors, fonts or Ant Design components |
| Embedded dashboards that inherit branding | Embedded surfaces inherit changes in the host product, so branding drift can reach customers | Confirm which embeds depend on Superset branding and who approves visual changes |
| Dashboards and reports to re-verify | More dashboards, charts and scheduled reports widen the visual test set | Build an inventory of dashboards and reports that carry branding, including exported PDFs and thumbnails |
| Staging environment | Without staging, testing happens in production and rollback becomes harder | Confirm a staging instance with a copy of the metadata database and the same theme configuration |
Questions buyers ask before rebuilding Superset branding
How much does a THEME_OVERRIDES migration cost?
The cost is the effort to rebuild your branding on the 6.0 theming system, plus the testing that proves it works. DeployOpen does not publish a price list, and a quote follows from a written scope. The main components are: auditing your current THEME_OVERRIDES, APP_NAME, CUSTOM_FONT_URLS and template settings; rebuilding tokens, fonts and the application name for each theme; and testing dashboards, charts and login pages. Costs rise with the number of themes, custom CSS, custom templates and chart plugins that read theme values. Ask any partner to itemize these in the quote, and to state which items are one-time and which recur at each upgrade.
How long does a theme migration take?
Duration depends on how much of your branding is custom and how many surfaces must be checked. Theme tokens are a small mapping exercise when the old settings are simple, but the review of dashboards, charts, embedded views and reports usually takes most of the time. The main duration drivers are the number of themes, whether you use custom fonts that must be hosted again, how many custom chart plugins depend on Ant Design components, and how many approvers must sign off on the visual result. Ask for a schedule with milestones in the written scope, not a single end date.
What does the work need from our own team?
Your team needs to provide the current configuration, the brand assets and the people who approve visual changes. Typically this means the superset_config.py file or equivalent settings, the logo and favicon files, the font files or hosting details, a list of the dashboards and charts that matter most, and a named approver for brand and accessibility. Your engineers should also provide a staging environment that mirrors production, so changes can be tested without affecting users. Confirm these inputs in the scope before work starts, since missing assets are a common cause of delay.
Can our own developers do the theme migration?
Yes, if they have front-end experience with React and Ant Design 5 and access to a staging Superset running the target release. The 6.0 theming system is configured through theme tokens rather than the older THEME_OVERRIDES dictionary, so the mapping is learnable. The harder parts are verifying every page that uses theme values, handling custom templates or plugins, and keeping the configuration in version control. Many teams do the simple mapping in house and bring in outside help for the review and test plan. Decide the split in writing so ownership of each deliverable is clear.
Can we keep our old branding settings during the 6.0 upgrade?
Not as they are. Superset 6.0.0 replaced THEME_OVERRIDES with a theming system based on Ant Design 5, so the old dictionary no longer drives the interface and must be translated into the new tokens. Superset 6.1.0 also changed the application name: APP_NAME no longer controls the browser title or frontend branding, which moved to the brandAppName theme token. CUSTOM_FONT_URLS was removed in favor of a per-theme fontUrls token. You can keep the visual intent of your brand, but the settings themselves need to be rewritten and tested on the release you run.
What should we ask a partner to include in a written quote?
Ask for a scope that lists each deliverable and the acceptance test for it. A useful quote states the inventory of current branding settings, the target Superset release, the mapping of each old setting to its new token, the handling of fonts and logos, the list of dashboards and pages in the test plan, the number of review rounds, and what is excluded. Also ask how changes are stored and deployed, whether you receive the configuration as code, and what a later upgrade to a newer release would require. Confirm the release notes the partner uses, including the Superset UPDATING notes at the project's UPDATING.md.
How does theme work fit into the wider 5.x to 6.x upgrade?
Theme migration is one workstream inside the upgrade, and it should run in the same staging cycle. The upgrade guide asks you to back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes. Theme changes depend on the release you land on, so plan the 6.0 theme rebuild and the 6.1 brandAppName and fontUrls changes together if you will cross both versions. Test branding with the same dashboards and reports used for functional checks, so visual and data regressions are found in one pass.
Where to confirm the token names for your target version
The authoritative source for breaking changes is the UPDATING.md file in the Superset repository, read together with the upgrade guide for the exact release you plan to deploy. Token names, font settings and removed configuration keys are recorded there, and they can change between minor releases, so treat the file as the spec for your build. Read the entries for every version between your current release and the target, not only the final one. Before writing any theme code, record the exact target version, open its UPDATING.md at the matching tag, and list each theming key your current THEME_OVERRIDES and APP_NAME settings depend on. Keep that list with the change ticket so reviewers can see where each value came from.
Confirm token names against the release you will run, not against the documentation for the latest development branch. The `brandAppName` token and the per-theme `fontUrls` token are the two names this migration depends on in 6.1, and their exact spelling and behavior should be checked in the notes for your version before you rely on them. If you are targeting a release where the Ant Design theme tokens are documented differently, the mapping in your code must follow that release. Ask your team to test the theme in a staging instance running the identical image and package versions, because a token that is valid in one release can be ignored or renamed in the next.
How DeployOpen scopes and delivers a Superset theme migration
DeployOpen plans and implements the move from THEME_OVERRIDES to the Superset 6.0 theming system inside your own infrastructure, starting with an inventory of what your current branding actually changes. The work runs as a fixed-scope engagement with deliverables and timelines agreed in writing before any build starts.
How we scope
- We inventory every existing THEME_OVERRIDES entry, APP_NAME and CUSTOM_FONT_URLS setting in your current configuration files.
- The written scope lists which theme tokens, brand names, fonts and dashboards are in and out of the migration.
- We agree which Superset version you are targeting, such as 6.0 or 6.1, since APP_NAME and font handling differ between them.
How we build
- We map each legacy override to an Ant Design 5 theme token or a per-theme fontUrls entry in a version-controlled theme file.
- We set brandAppName for browser title and frontend branding where your target release requires it, then verify the result in a staging instance.
- We test representative dashboards, charts and login pages across light and dark variants, recording each difference from the old branding.
How we hand over
- You receive the theme definition, configuration changes and font assets in a repository you own, with a record of every mapped setting.
- The handover document explains each token, which legacy setting it replaced and how to change it safely during future upgrades.
- We walk your platform and design owners through the staging test results before any change reaches production.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the migration is complete.
- A retainer can cover re-running the dashboard visual checks when you move to the next Superset release line.
- Changes to brand assets or fonts after handover can be scoped as a separate, written change to the agreed deliverables.
