What Apache Superset thumbnails are and when teams enable them
If you are an admin who wants visual previews of dashboards and charts in Superset's dashboard and chart lists, you are asking for a feature that is not free to run. According to the Superset architecture documentation, dashboard thumbnails require the caching layer and the worker components, along with alerts and reports and async queries. In other words, thumbnails are not a standalone display setting. Before you flip anything on, confirm that you already run, or have planned, a caching layer (most installations use Redis) and Celery workers that can take on the extra job. If you do not, enabling thumbnails means adding that infrastructure first.
Thumbnails are worth enabling when the list views are how people find work. A team with a large library of shared dashboards, where users pick by appearance rather than by name, gets real value from previews. A small internal deployment with a handful of dashboards usually does not justify the added components, and the same effort is better spent on the caching and worker setup that alerts, reports and async queries need anyway. Because the worker tier is shared across those features, the decision is often less about thumbnails alone and more about whether your Superset will run workers at all.
Decide early, and write the decision down with the owner of the worker and cache services. Confirm with your Superset version's documentation which thumbnail settings and dependencies apply to the release you run, since these pages change between versions. Then plan for the recurring load that thumbnails add to the worker tier, because every thumbnail is rendered work that competes with reports and queries. Teams that skip this step tend to discover the cost after users start opening the list views.
Which thumbnail settings fit which deployment
Thumbnails are controlled by a feature flag. Leaving it off is the simplest option: list pages show no generated previews, and no thumbnail work reaches the workers. Turning it on adds a dependency chain. Thumbnail generation runs as an asynchronous task, so the caching layer and Celery worker components must already be running and healthy before the flag is useful. Enabling it on a deployment that has only the web tier is a common cause of thumbnails that never appear.
- Flag off: no extra worker load, no headless browser work, and no thumbnail storage to plan for.
- Flag on for a pilot: suitable when a small group of builders wants previews and you can watch worker queues before wider rollout.
- Flag on for all users: the workers and cache must be sized for every dashboard list view that triggers generation.
- Staging first: enable the flag in a copy of production to measure the effect on queues before changing live settings.
- Rollback: confirm that turning the flag off hides previews cleanly without breaking list pages.
Before you change the flag, confirm with your Superset release notes which configuration keys apply to your version.
Once thumbnails are generated, they are stored in a cache so list pages do not regenerate them on every request. The backend you choose decides where that data lives, how much memory or disk it uses, and who can read it. Redis is the backend most installations already run for Celery and other caching, so it is often the natural fit. A filesystem or object-style store may suit teams that want the cache outside Redis, but that choice needs its own backup and eviction planning.
- Shared backend for multiple web replicas: use a store that every web replica and worker can reach, or thumbnails will differ by pod.
- Timeouts: set cache lifetimes that match how often dashboards change, and confirm the timeout keys in the configuration reference for your version.
- Eviction under pressure: a small cache will evict thumbnails and cause regeneration, which shifts load back to workers.
- Sensitive content: thumbnails show dashboard content, so restrict access to the cache store the same way you restrict the dashboards themselves.
- Redis outage: agree on what users see when the cache is unavailable, since generation may fall back to workers.
Ask your platform team which cache store is already monitored and backed up, because adding a new store adds operational scope.
On a single host, the web server, Celery worker, beat scheduler and cache often share one machine or a small Docker Compose stack. This layout is easy to reason about and works for small user counts and pilots. The trade-off is that headless browser rendering competes for CPU and memory with queries, report delivery and the web tier. A thumbnail burst after a dashboard list refresh can slow interactive use on the same host.
- Shared resources: headless browser processes need memory headroom beyond the Superset processes themselves.
- Queue isolation: run a dedicated worker process for thumbnail work so a long queue does not block reports or async queries.
- Local storage: if you use local cache storage, plan disk space and cleanup on that host.
- Restart behavior: a single restart takes down the web tier, workers and cache together, so schedule maintenance windows.
- Growth path: keep configuration in version control so the same settings can move to Kubernetes later.
Check the resource profile of a test thumbnail run on the actual host class before enabling the feature for users.
On Kubernetes, thumbnail workers can run as their own deployment with their own resource limits, separate from web replicas. This lets you scale the thumbnail queue without adding web capacity, and it keeps headless browser memory use from evicting the web pods. The cost is more moving parts: a broker, a result backend, a beat scheduler and image dependencies must all match the Superset version you run. For Kubernetes installs, the official Helm chart is documented for the 6.1.0 release, but the current development documentation marks it as deprecated and points new deployments to the Apache Superset Kubernetes Operator, which is in alpha.
- Dedicated worker deployment: set requests and limits for thumbnail workers based on measured runs, not guesses.
- Autoscaling: scale on queue depth where your metrics allow it, and keep a single beat scheduler.
- Image choice: confirm the image includes the headless browser stack your version needs.
- Storage: use a shared store for the thumbnail cache when several replicas read it.
- Operator risk: the operator is alpha, and its custom resource schemas may change between releases, so pin versions and test upgrades.
Confirm your chart or operator choice and version with the Superset Kubernetes documentation before you write manifests.
How to enable thumbnails in a production Superset
This sequence turns on dashboard and chart previews in a production Superset without disturbing the web tier or the warehouse. Each step ends with a check, so you confirm the foundation works before adding the next layer.
Confirm the metadata database and caching layer
Before touching thumbnails, confirm that Superset runs on a supported metadata database, PostgreSQL 10 to 17 or MySQL 5.7 or 8.x, rather than the SQLite default or the Docker Compose PostgreSQL container, which are not recommended for production. Confirm that Redis is in place as the caching layer, because the architecture documentation says thumbnails require the caching layer and worker components. The platform team owns this check, and it is done when a dashboard loads, a chart's data is cached on a second request, and the metadata database has a tested backup.
Enable the thumbnail feature flag
Turn on the thumbnail feature flag in the Superset configuration file, then restart the web and worker containers so both read the same settings. Confirm the exact flag name and any related settings against the configuration documentation for your Superset version, because flag names change between releases. The check is that dashboard and chart list pages render a placeholder where a preview will appear, with no errors in the web server log.
Configure Celery workers and beat
Start a Celery worker that consumes the queue used for thumbnail jobs, and run a single beat scheduler if your configuration uses scheduled thumbnail tasks. Keep the worker on the same secret key, metadata database and Redis broker as the web tier so it can read the same objects. Ask whether thumbnails share a queue with async queries and reports, since a busy queue delays previews for everyone. The check is that the worker reports ready, the broker shows it connected, and a test task completes.
Install a headless browser the workers can reach
Thumbnail images are rendered by a headless browser, so install one on the worker host or in the worker image and confirm the worker can reach the Superset web endpoint it will load pages from. Network policy matters here: a worker that cannot resolve the internal web URL or that sits behind a proxy will fail silently. Confirm the browser and driver versions against the Superset documentation for your release. The check is a manual render: the worker should open a test dashboard URL and produce an image file without errors.
Set the thumbnail cache
Point the thumbnail cache at the Redis instance or other storage your configuration defines, and set a timeout that fits how often dashboards change. A short timeout means more rendering and more worker load, while a long one can show stale previews after a dashboard edit. Ask your team to size the cache with the worker plan, because every cached preview consumes memory. The check is that a second request for the same dashboard list returns the cached image without a new worker job appearing in the queue.
Verify previews generate and cache
Edit a test dashboard, load the dashboard list, and confirm that a fresh preview appears within the time your team considers acceptable for the workload. Then load the list again and check that the browser sends a conditional request and receives a not-modified response, which shows ETags are working. Watch the worker logs and queue depth during a list load with several dashboards to see the rendering load. Done means previews appear, refresh after edits, and do not regenerate on every page view.
Record the operating baseline
Write down the worker concurrency, queue name, cache timeout, browser version and the list page load you tested, so the next upgrade or scaling change has a reference point. Include who owns the worker queue and who receives alerts when a thumbnail job fails. Ask your partner or internal team to include these items in the upgrade runbook, since the upgrade documentation calls for testing in staging first. The check is a short runbook entry that another engineer can follow to reproduce the setup.
How the thumbnail cache and ETags reduce repeat work
Thumbnails are expensive to produce because Superset renders each image with a headless browser on a Celery worker, so the goal is to generate each image once and let browsers and the server reuse it. Superset stores generated thumbnails in its cache layer, and the web tier answers repeat requests from that cache instead of sending work to the workers again. Browsers add a second layer: the response carries an ETag, and a browser that already holds the image sends that tag back so the server can reply that nothing changed. The practical effect is that a dashboard list full of unchanged thumbnails should cost little after the first load, but only if the cache backend and the reverse proxy in front of Superset pass these headers through unchanged.
Regeneration happens when the cache entry for a dashboard or chart is missing, expires, or is invalidated. Changes to the dashboard layout, its charts, or the underlying dataset can trigger a new render, and so can a cache timeout set in configuration. Because the exact cache key format, the timeout values and the invalidation hooks differ between releases, confirm the thumbnail cache keys and invalidation behavior against the Superset version you run before you rely on them for capacity planning. The Superset configuration documentation is the starting point for the cache settings that apply to your release.
Test this behavior in staging rather than assuming it. Load a dashboard list twice, confirm that the second load returns cached or not-modified responses, then edit a chart and check that only the affected thumbnail is rebuilt. Watch the worker queue during that test, because a proxy that strips ETag or Cache-Control headers will quietly send every request back to the workers. Record what you find, since it sets the baseline for the worker sizing decisions covered in the Celery scaling section.
What thumbnails add to worker load and where it spikes
Thumbnails look like a small visual extra, but each one is produced by a headless browser running on a worker. The cards below cover the load sources that matter most, and where they tend to pile up on shared infrastructure.
Headless browser rendering cost
Each thumbnail requires the worker to load a dashboard or chart page in a headless browser, wait for it to render, and capture an image. This is far heavier than running a SQL query and returning rows. Ask your team to measure how long a single thumbnail takes on your hardware, because that time multiplies across every dashboard and chart the list views request. Watch worker CPU during list-page tests before you size the pool.
Bursts after deployments
Thumbnails are generated when users open dashboard and chart lists, so a new release or a cleared cache can trigger a wave of rendering at the same moment. Many people opening the same lists after a deployment will request the same images at once. Plan for this spike during rollout, not only for steady daily traffic, and test the first-hour behavior in staging with realistic user counts.
Competition with queries and reports
If thumbnails share a Celery queue with async SQL Lab queries, scheduled reports, or alerts, a burst of rendering can delay work users are waiting on. A report that should send at 7 a.m. may wait behind thumbnail tasks. Separate queues per workload are the usual control, and you should confirm how your chosen broker and worker settings route each task type before go-live.
Memory use of browser processes
Each headless browser process holds its own memory while it renders a page, and concurrent renders multiply that footprint. Browser memory is often higher than the Python worker's memory, so a concurrency setting that looks safe on paper can exhaust a container under load. Measure peak memory per render with your largest dashboards, then set container limits and worker concurrency from those measurements.
Cache misses after restarts
Thumbnails are stored in a cache, so a restart, cache flush, or an expired cache leaves every image to be regenerated. Restarts during maintenance can therefore create the same load pattern as a release. Confirm where your thumbnail cache lives, how long entries persist, and whether it survives a Redis or worker restart before you schedule maintenance windows around heavy user activity.
Questions teams ask before enabling thumbnails
What does enabling dashboard and chart thumbnails involve, and who does the work?
Enabling thumbnails means turning on the feature in Superset's configuration, confirming that the caching layer and Celery workers that generate and store the images are running, and checking that the headless browser and cache settings work for your users. The Superset architecture documentation says thumbnails require the caching layer and worker components, so the work spans the web application, the metadata database, Redis and the worker tier. DeployOpen plans and implements this under a written, fixed scope that covers configuration, worker placement, staging verification and handover. Your platform team usually runs the infrastructure afterward, so ask the partner to name which pieces are in scope and which remain yours.
Can our own team enable Superset thumbnails without a partner?
Yes, if your team already operates Superset with Celery workers and Redis and can test changes in staging before production. Teams without those skills usually find the effort sits in verification rather than in the setting itself: confirming that workers pick up thumbnail tasks, that the cache holds the images, and that the web tier serves them under normal traffic. Upgrade notes in UPDATING.md can also change behavior between versions, so check them against the version you run. Consider a partner when nobody on the team has run Celery in production or when the dashboards feed regulated reporting. DeployOpen works inside your own infrastructure, so ownership of the running system stays with you.
What makes thumbnail work take longer or cost more?
The main drivers are how much of the required stack you already run, how large your dashboard catalog is, and how isolated your network is.
- Existing Redis and Celery: if they are missing or unmanaged, much of the effort moves into building them first.
- Environment: air-gapped networks, restricted egress and internal certificate authorities add test steps for the headless browser.
- Content volume: large dashboard catalogs and frequent edits increase how many thumbnails must be generated and refreshed.
- Access model: confirm which user's permissions a thumbnail is rendered with, since row-level security and role rules affect what appears in the image.
- Deployment path: the Kubernetes Operator is in alpha, and the Helm chart is marked deprecated in current development documentation, so your choice affects later rework.
Ask which of these apply to your environment before comparing quotes.
Does enabling thumbnails require Redis and Celery?
Yes. The Superset architecture documentation states that dashboard thumbnails require the caching layer and worker components, and that most installations use Redis and Celery for them. Celery workers run the thumbnail generation tasks, and the caching layer stores the results so they are not rebuilt on every request. Check the configuration documentation for the broker, result backend and cache settings your version expects. Confirm whether thumbnail tasks get a dedicated queue so that reports and async queries do not compete with them. The metadata database must remain PostgreSQL or MySQL for production, because the SQLite default is not recommended there. Test the full path in staging before users depend on it.
How do dashboard thumbnails affect load on the data warehouse?
Thumbnails can add warehouse queries because generating an image renders the dashboard or chart, which runs the queries behind it unless results are already cached. The effect depends on how many dashboards are thumbnailed, how often they regenerate and whether the cache holds chart results long enough to serve the render. Load also rises when many users open dashboard lists at the same time and trigger new thumbnail tasks. Before enabling, confirm which database account runs the render, the cache timeouts for charts and datasets, and how thumbnail refresh is scheduled. Warehouse teams often ask for a dedicated service account or query limits, so put those requests into the written scope. Measure query volume in staging before and after the change.
What does the Kubernetes Operator's alpha status mean for thumbnails?
It means the Operator's custom resource schemas can change between releases, so a deployment built on it may need rework during upgrades. According to its documentation, the Apache Superset Kubernetes Operator is built with the Go Operator SDK, is in alpha and uses a v1alpha1 API. Thumbnails depend on the worker and cache components, so a schema change could affect how those components are declared. Pin the Operator version, keep custom resources in version control and test every upgrade in staging. If your Kubernetes platform requires a supported deployment path, compare the Operator with the Helm chart, which current development documentation marks as deprecated. Ask the partner how they will handle schema changes in your environment.
What should we ask for in a written quote for thumbnail work?
Ask for a quote that lists scope, deliverables and assumptions in writing before work starts, since most DeployOpen engagements are fixed-scope. The quote should name the Superset version, the deployment method, the infrastructure covered and the testing included. Ask for:
- The components in scope: configuration, Redis, Celery workers, the headless browser setup and the cache.
- Who runs staging tests and which pass criteria apply.
- Which warehouse accounts or query limits change, if any.
- What is one-time (setup and verification) and what recurs (upgrades, monitoring or retainer support).
- The assumptions about existing infrastructure that you are responsible for.
Also ask how upgrades are handled, since the upgrade guide calls for a metadata database backup, superset db upgrade, staging tests and a review of UPDATING.md.
How DeployOpen scopes and delivers thumbnail work
Thumbnail work starts with a written scope, because the decisions that matter are made before any configuration changes. DeployOpen agrees in writing which dashboard and chart lists will show thumbnails, whether the thumbnail feature flag is enabled for all users or a defined group, which Celery queue will carry thumbnail tasks, how the headless browser is packaged and where it runs, and which thumbnail cache backend stores the images. The scope also names what is out of scope, such as changes to the Celery beat schedule or the rest of the worker fleet, so the boundary is clear before the first deployment. Ask for this scope to be written with explicit acceptance checks, and confirm in writing who owns the headless browser image and its patching.
Worker sizing is agreed with your team rather than assumed. DeployOpen works with you to establish how many people open dashboard lists, how often thumbnails are regenerated, and whether thumbnail jobs share a queue with async queries, reports and cache warmup. The result is a worker count, concurrency setting and queue layout that you can review. Confirm with your platform team which Redis or broker capacity, and which Kubernetes autoscaling rules if any, are already in place, since thumbnail generation adds load that recurs as dashboards change. Ask for the sizing assumptions and the load test method in the quote, so you can rerun them when usage grows.
Verification happens in staging before anything reaches production. The checks cover that thumbnails render for representative dashboards and charts, that the thumbnail cache stores and expires images as configured, that ETag responses return 304 when nothing has changed, and that failed headless browser runs are logged and retried without stalling other worker tasks. After go-live, DeployOpen can support the platform under a retainer that covers monitoring of worker queues, upgrades that touch the headless browser or Celery versions, and retesting when Superset versions change. Retainer scope, response expectations and what happens to in-flight changes should be written into the agreement, and you should confirm them against your own change process before signing.
