How custom fonts in Apache Superset fit your brand and security rules
A platform or BI lead usually asks for corporate fonts for one reason: dashboards should look like the rest of the company's material. On a network that blocks outside requests, that request runs straight into a security rule. Font loading in a Superset theme is a browser behavior, so the font file has to be reachable from every user's browser, and the Content Security Policy (CSP) that your organization sets must allow it. Before you choose a font source, confirm with your security team which origins the CSP permits for font-src, and whether the policy is set by Superset, by a reverse proxy in front of it, or both.
Font work also has a second surface that browser testing hides. Reports and screenshots are rendered by the alerts and reports worker, not by the viewer's browser, so a font that loads for an analyst can fall back to a system font in a scheduled PDF or thumbnail. The fallback is easy to miss until a stakeholder compares two outputs side by side. Check the report rendering path in your own environment, not just the dashboard view, and confirm which fonts are installed in the image or on the worker host. The Superset architecture documentation describes which components run those jobs, which tells you where the fonts must be available.
Superset is licensed under Apache-2.0 and has no paid edition, so the font work is engineering and configuration effort on infrastructure you already run, plus any licensing review your organization applies to the font files themselves. Font work sits within the broader customization and plugins group, alongside branding, theme tokens and chart overrides. It depends on the theme decisions made there, and it feeds the translation and map tile work that follows. Settle which corporate fonts you must use, where their files will be served from, and how the CSP will change before you write any theme JSON.
Which font loading option fits your environment
This table compares three ways to load corporate fonts into a Superset theme: a corporate CDN, the same origin as Superset, and a self-hosted path inside a restricted network. Read each row as a question to answer for your environment, then check the CSP and licensing rows before choosing. The main takeaway is that the option you pick decides which CSP font-src entries you must add and who must confirm the font license.
| Decision factor | Corporate CDN | Same origin as Superset | Self-hosted in restricted network |
|---|---|---|---|
| Font URL in the theme | Absolute URL to the CDN file, set in the theme's font references | Relative or same-host URL served by the Superset web tier or proxy | Internal URL on your file server or artifact store, reachable from browsers |
| CSP font-src change | Add the CDN host to font-src; confirm the exact host with your security team | Usually none beyond the default self policy; verify in your header configuration | Add the internal host only if it differs from Superset's origin |
| Browser access from the network | Requires outbound access from user devices to the CDN | No extra egress; fonts load from the same site users already reach | Works without internet access once fonts are copied in |
| Licensing check | Confirm the CDN license permits your use and hosting terms | Confirm the license permits redistribution inside your image or server | Confirm the license permits copying into your own infrastructure |
| Caching behavior | Shared CDN caching may help across other sites; depends on the provider | Cached with Superset static assets under your own headers | Cached by your proxy or browser under settings you control |
| Best fit when | Many internal apps already use the same CDN and it is approved | Single Superset instance and a strict policy on third-party hosts | Air-gapped or highly restricted networks, or fonts must not leave your estate |
| Single theme versus several themes | One font URL reused across themes is simple to maintain | Each theme points to the same files, so updates apply everywhere | Each added theme or font weight adds files to copy and verify |
| What to confirm before rollout | CDN availability target, host name and CSP change approval | Header and proxy configuration for font MIME types and CORS needs | Font file set, update process and where the copies are stored |
Setting up custom fonts in a Superset theme
This sequence takes a corporate font from license check to a verified dashboard and rendered report in staging, so the font loads from an origin you approved and the change can be promoted with evidence.
Confirm font files and licenses
Your brand or legal owner confirms which font families, weights and styles the organization may serve from its own servers or a third-party host, and records the license terms that allow web embedding and self-hosting. Collect the font files in web formats such as WOFF2 and note each family name exactly as it should appear in the theme. Confirm the license with the font vendor if the terms do not mention web use. Done when you have a signed-off list of families, weights, file names and the origin each file will be served from.
Stage font files on an approved origin
Place the approved files on the web server or asset host that your Superset deployment is allowed to load from, which is often the same origin as the application or a dedicated static host inside your network. Keep the paths stable so the theme and the CSP entries can point at them without later edits. Where your network blocks public CDNs, host the files only on internal infrastructure and confirm with your network team that the hostnames resolve for users. Done when a browser can open each font URL directly and receives the font file with a success response from the chosen origin.
Define font families in the theme
Add the font families and their @font-face declarations to the theme JSON that your administrators load into Superset, using the same family names you recorded earlier. Set the base font token and any heading or chart font tokens that your theme uses, and keep a fallback stack of system fonts after each corporate family. Store the theme file in version control so changes are reviewed like other configuration. Done when the theme validates in the Superset theme administration screen and the page renders with the new family name listed in the computed font of body text.
Add font-src entries to the content security policy
Edit the Content Security Policy headers that Superset sends, adding the origin that serves your font files to the font-src directive and keeping the existing directives intact. Check how your reverse proxy or the Superset configuration sets these headers, because a second layer in the proxy can override the application value. Record the exact directive text in your change record. Done when the response headers for a Superset page list the approved origin under font-src and no other new origin appears.
Deploy the change to staging
Apply the theme, the static files and the header change to a staging instance built the same way as production, using the same container image, proxy configuration and network path. Keep production untouched until the checks below pass. Confirm the theme is applied to the intended scope, whether system-wide or per dashboard, before testing. Done when staging serves the new theme and headers and your change record shows the exact versions of the theme file and proxy configuration that were deployed.
Verify fonts in the browser network panel
Open a dashboard in staging in a browser with developer tools, reload with the network panel open and filter for font requests. Each corporate font file should load with a success status from the approved origin, and no font request should be blocked by a Content Security Policy error in the console. Repeat in a second browser and from a user account with a different role to confirm the theme is not dependent on one session. Done when every corporate font weight used in the dashboard appears as a successful request from the approved origin with no CSP violations logged.
Check a rendered report and screenshot
Generate a scheduled or on-demand report for the same dashboard in staging, and compare the rendered output and any dashboard screenshot with the browser view. The screenshot is produced by a headless browser on the worker side, so confirm that it can reach the same font origin from the worker network and that the corporate font appears rather than a fallback. Note any difference in weight or line spacing and record it for the release decision. Done when the report and screenshot show the corporate font, and the worker logs contain no failed font requests.
Security settings to review when fonts load from outside
Loading a corporate font from a CDN or a font host changes what the browser is allowed to fetch, and that change touches your content security policy, your licensing position and your release process. The cards below cover the decisions and checks that connect those areas for a Superset deployment.
Widening font-src deliberately
Adding a font host means editing the font-src directive in the Content Security Policy that Superset sends with its responses. Each host you add is a new origin the browser will trust for font files. Keep the list short, name exact hosts instead of wildcards, and record which theme or dashboard needs each one so a later review can remove hosts that no longer have an owner.
Third-party CDN against self-hosting
A third-party font CDN is quick to set up and needs no file handling on your side, but every page view sends a request to that provider, which can expose user IP addresses and adds a dependency your network may block. Self-hosting keeps requests inside your own origin and works on restricted networks, at the cost of packaging font files into your image or static assets and keeping them current.
License terms for font files
A font license decides whether you may host, embed or serve a font file to every viewer of a dashboard, and many commercial licenses limit web embedding or count page views. Before self-hosting, confirm the license covers your web use, your number of users and your hosting model, and keep the license file with the asset. Open-source fonts usually carry their own license text, so check that text instead of assuming it.
Change control for theme and header settings
Font URLs live in theme JSON and CSP headers live in superset_config.py or your reverse proxy, so a font change can be made in two places by two teams. Store both in version control, require review for changes to font-src, and tie each theme change to a ticket that names the hosts it adds. Theme administration in the UI should be limited to a small group who can export what they changed.
Verifying headers after upgrades and restarts
Headers set in a reverse proxy can be dropped or overwritten during a proxy change, and an upgrade can alter what Superset sends by default. After each upgrade, restart and proxy change, request a dashboard page and inspect the response headers and the browser console for blocked font loads. Add this check to your upgrade runbook, and confirm the exact header behavior for your Superset version in the upgrade notes before you rely on it.
Fonts in exports and report rendering
Dashboard thumbnails and scheduled reports are rendered by a headless browser on the worker side, which fetches the same fonts. If the worker cannot reach an external font host, reports and screenshots fall back to other fonts and look different from the live dashboard. Test a scheduled report from the worker's network, not from your laptop, and confirm the worker's egress rules allow the same font sources the browser uses.
Why fonts can differ in reports and screenshots
A font that renders correctly in a user's browser can still be missing from the output Superset sends by email or stores as a thumbnail. Alerts, reports, async queries and dashboard thumbnails depend on the caching layer and the worker components described in the Superset architecture documentation, and most installations run these with Redis and Celery. The headless browser that renders a dashboard for a scheduled report or thumbnail runs on the server side, not in the viewer's browser. That means the font URL in your theme, and any font-src allowance in your Content Security Policy, must work from the network location of the worker or report server as well as from user browsers. A font served only from a CDN that users can reach but the worker cannot will look correct on screen and wrong in every delivered PDF or PNG.
Plan a test for each output path before you approve the theme. Open the same dashboard in a browser, export it as a PDF, run a test report to a real inbox, and check the thumbnail the dashboard list shows after a cache refresh. Compare the glyphs, weights and line breaks in each output against the browser view. Confirm which fallback fonts exist on the image that runs the report and thumbnail processes, because the container may not include the corporate font or the system fonts your designers assume. Ask your platform team whether that image can be rebuilt with the font files installed, and confirm with the Superset release you run how the worker reaches the font host, since this depends on your network layout and version.
Record the results as a short acceptance checklist: browser, export, report and thumbnail, each with a screenshot and the name of the fallback font if one was used. Repeat the check after every Superset upgrade, base image change or CSP edit, because any of these can change which fonts load. Treat a mismatch in a scheduled report as a defect in the theme or the image, not as a cosmetic issue, since executives often receive reports without ever opening Superset.
Limits to confirm in your environment
Font loading in Superset depends on details that change between releases and deployments, so the limits below are checks to run rather than assumptions to carry into a build. Each card names one item to confirm with the vendor documentation and with a test in a staging instance that matches production.
Theme keys that accept font families
Confirm which theme tokens in your target Superset release accept font family values, and which ones fall back to the default stack. Font keys can differ between the base token set and component-level overrides, so a font set in one place may not reach headings, table cells or chart labels. Build a short test theme that sets each key you plan to use, then review a dashboard, a chart and an explore view. Record the exact release you tested so the result can be repeated during upgrades.
Per theme or global scope
Check whether a font change applies only to the theme where it is set or to every dashboard in the instance. Teams often assume a corporate font will apply everywhere after one edit, and then find that dashboards on a different theme keep the old typeface. Test a dashboard that uses a system theme and one that uses a dashboard-specific theme, and confirm which one a reader sees. Write the result into your theme governance notes so that a later edit does not change more than intended.
Cached assets after font changes
Confirm how browsers and any proxy or CDN in front of Superset handle the stylesheet and font files after you change a font URL or swap a file. Cached copies can keep serving the previous typeface to users who already loaded the application, and a shared cache can hold it for other users too. Plan a cache-busting approach, such as versioned file names, and test it by loading the application in a clean browser profile and in one that already has a session. Ask your platform team which cache layers sit in the path.
Metadata database and Superset version pairing
Confirm that your chosen Superset version supports the metadata database version you run. The configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported versions, but support for a given Superset release should be checked against its own documentation before you change either side. Font work does not touch the database, but a release or database change in the same window can make font test results hard to interpret. Keep the two changes in separate windows where possible.
Font file hosting and CSP rules
Confirm that the font host is allowed by the Content Security Policy your deployment sends, and that the font file type is served with a correct content type. A font URL can load in a test browser and still fail in production when a reverse proxy or header policy blocks it. Check the effective headers from the browser developer tools on each page type you use, including embedded or public views if you use them. Record which origin the fonts load from so that a security review can approve it.
Questions teams ask before loading custom fonts
How much does it cost to load custom fonts in Superset?
The cost depends on the written scope, which is quoted after the work is defined, and DeployOpen does not publish a price list. Font loading looks small, but the effort grows with the number of themes that need fonts, the number of font weights and styles per family, whether fonts come from a vendor CDN or are self-hosted, and how much report and screenshot testing is required. Ask for each cost driver to be itemized in the quote, and ask which items are one-time (initial font setup and testing) and which recur (re-testing after Superset upgrades or font file updates).
How long does custom font setup take?
No duration is published for this work, so the timeline should come from the written scope. The main variables are the number of themes, whether your security team must approve new font origins in the Content Security Policy, whether fonts must be served inside a restricted network, and how many rendering checks are needed across PDF reports, PNG thumbnails and browsers. Ask for milestones that separate approval of font sources from build, testing and rollout.
What does our team need to provide for font work?
Your team needs to provide the licensed font files or web font links, the brand guidelines that define which weights and styles each theme uses, and a list of the Superset instances and themes that need the fonts. Security or network teams must also confirm which origins the browser may load fonts from, and whether the Superset host can reach external font servers. Without these inputs, the work stalls at the approval step, so confirm owners and turnaround for each item before the scope is signed.
Can our own team load custom fonts without a partner?
Yes, a team with front-end experience and access to the Superset theme configuration can usually load fonts through theme settings and a Content Security Policy change. The harder parts are the ones that need review: confirming that the fonts are licensed for web use, making sure the CSP font-src change does not weaken other directives, self-hosting fonts for air-gapped networks, and checking that PDF reports and thumbnails render the same fonts as the browser. A partner is useful when the team wants that testing and documentation done once and repeated after upgrades.
Are corporate fonts licensed for use in a web application?
Usually not by default. A font license bought for desktop or print use does not automatically cover serving the font files from a web server or loading them in a browser for many users. Check the license terms for web embedding, self-hosting rights, the number of domains or page views allowed, and whether the vendor permits hosting the files inside your own network. Your legal or procurement team should confirm this before any font file is copied into a Superset image or theme.
What breaks when we upgrade Superset with custom fonts?
Font settings live in theme configuration and in the Content Security Policy, so an upgrade can change how those are read or can add new asset paths that the CSP blocks. Check the breaking change notes in UPDATING.md for each target version, and test a copy of production in staging before rollout. Also re-check that self-hosted font files are still served at the same paths, and that PDF reports and thumbnails still render the intended typeface, since those run through a separate rendering process.
How do you scope a custom font engagement?
A written scope starts with an inventory of the themes, the font families and weights each theme needs, the font origins your security team approves, and the environments where fonts must render, including restricted networks. It then lists deliverables such as theme configuration, CSP changes, self-hosted font files, a rendering test matrix covering the browser, reports and screenshots, and handover documentation. The scope should also state what is out of scope, such as logo or color work covered by separate branding or chart work, so the quote reflects only what was agreed.
Does restricting the Content Security Policy affect font loading?
Yes. Fonts are governed by the font-src directive in the Content Security Policy, so a browser blocks any font loaded from an origin that is not allowed there. Adding a vendor or CDN origin widens what the page may load, which is a security decision that should be reviewed rather than granted by default. Ask your security team to approve each origin explicitly, and confirm that self-hosted fonts load from the same origin as Superset so no new allowance is needed.
Keeping font settings intact through Superset upgrades
Font configuration is part of your theme and your deployment, so it should be treated as something an upgrade can change. Before any Superset upgrade, back up the metadata database, since that is where theme records are stored, then run the upgrade in staging first. The Upgrading Superset documentation asks for a database backup, superset db upgrade and superset init, and a staging test before production. Keep a copy of every font URL, the @font-face or fontUrl values your themes reference, and any self-hosted font files in version control so you can restore them if a theme fails to load after the upgrade.
Read UPDATING.md for every version between your current release and the target before you change anything. Look for changes to theme handling, token names, Content Security Policy defaults and static asset paths, since any of these can stop a corporate font from loading without an obvious error. Confirm with your own staging environment whether the theme you exported still applies, whether the font files resolve from the same paths, and whether font-src in your CSP still allows the font host. Also check reports and screenshots generated by Superset, because thumbnail and export rendering runs on the worker and may pick up fonts differently from the browser.
Treat the 7.0.0rc2 pre-release listed on the apache/superset releases page as a test target only, not a production upgrade path. Pre-releases can change theme behavior before a stable release, so use one only to get early warning about issues you will need to fix. After every upgrade, including patch releases, recheck each theme, dashboard and chart that uses custom fonts, and compare them against your approved reference screenshots. Record the result as part of your change record, so the next person can see which theme settings were verified and against which Superset version.
How DeployOpen scopes and delivers font and theme work
DeployOpen treats custom fonts in Apache Superset as part of the theme, the Content Security Policy and the deployment image, not as a stylesheet tweak. We agree the font sources, the restricted-network constraints and the reporting checks in writing, then build and hand over the change inside infrastructure you control.
How we scope
- We list every font family, weight and theme that must render in dashboards, reports and embedded views.
- We confirm where font files may be hosted, whether a CDN is allowed and which domains the font-src directive must permit.
- We agree in writing which Superset themes, screenshot checks and fallback fonts are in the fixed scope.
How we build
- We configure theme font URLs per theme and adjust the Content Security Policy only for the origins the scope approves.
- We self-host font files in the deployment image when the network is restricted, and document the license terms for each font.
- We test rendering in dashboards, alerts and report screenshots in a staging instance before any change reaches production.
How we hand over
- We deliver the theme configuration, font asset inventory, CSP changes and build steps as versioned files your team can review.
- We document how to add a font, rotate a font file and roll back a theme change, with the checks that confirm each step.
- We walk your engineers through the screenshot and report validation so they can repeat it after each Superset upgrade.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer, including re-checking fonts after Superset releases.
- We can review font and theme changes against your upgrade notes so that rendering regressions are caught before rollout.
