# Superset's compose file is marked unsupported for production, and its version number comes from package.json

> A read of apache/superset: what the warning at the top of docker-compose.yml means for a real deployment, why the Python package version is read out of the Node manifest at build time, which dependency the project deliberately leaves unbounded, and why the default container image ships without translations.

**apache/superset** — Apache Superset is a Data Visualization and Data Exploration Platform.

- Repository: https://github.com/apache/superset
- Website: https://superset.apache.org/
- Stars: 74,921 · Forks: 18,386
- Language: Python
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/apache-superset

## The compose file carries its own production warning, and four of them exist

The first comment block in docker-compose.yml is the most useful thing in the repository for a deployer. It states that docker compose is not supported for production environments, and that anyone choosing it anyway must create their own environment file at `docker/.env` with their own unique random secure passwords and `SECRET_KEY`. The shipped file is a development stack, and the difference is not a matter of scale.

There are four compose files at the top level, `docker-compose.yml`, `docker-compose-light.yml`, `docker-compose-non-dev.yml` and `docker-compose-image-tag.yml`, and two Dockerfiles, `Dockerfile` and `dockerize.Dockerfile`. Choosing between them is a decision the readme does not make for you, and the light and non-dev variants exist precisely because the default one is not what a server should run.

The volumes are where a deployment's state lives. The compose file mounts host directories for the docker configuration, the `superset` package, `superset-core` and `superset-frontend` sources, the tests and a local extensions folder, and it names two volumes, one for `superset_home` and one for `superset_data`. Those two hold the metadata database and the uploaded artefacts, and they are the things to back up; nothing in the readme describes that. The user anchor in the file is also set to root, which is a development convenience rather than a choice to carry to a server.

## The Python version is read from the Node manifest during the build

The packaging scripts are unusual in a way that explains a lot of the project's behaviour. The manifest marks its version, its scripts and its entry points as dynamic, which means they are not written in `pyproject.toml` at all, and `setup.py` supplies them.

The version itself comes from the frontend. The script opens `superset-frontend/package.json`, reads its version field, and uses that as the Python distribution's version. It then asks git for the current commit, and it does so inside a try block whose except clause returns an empty string on any failure.

```bash
git rev-parse HEAD
```

The result is written into `superset/static/version_info.json` together with the version string, and the file is created as a side effect of the build, so the value the interface reports about itself is a build artefact. Two consequences. A build from a source distribution or from a tarball with no git metadata produces an empty commit identifier and no error, because the except clause is broad by design. And the version a Superset instance reports is the frontend's version, so a mismatch between the two manifests cannot happen by accident, but a stale frontend manifest would silently misreport the whole installation.

## Python 3.11 is the floor, and only two versions are declared as tested

The project metadata sets a hard floor and a narrow claim. The floor is `requires-python = ">=3.11"`, so anything older is refused at install time. The claim is in the classifier list, which names only Python 3.11 and 3.12.

```toml
requires-python = ">=3.11"
```

Those two statements disagree about the edges. A machine on 3.13 satisfies the floor and installs cleanly, while the classifiers say nothing about it, so the project is implicitly tested on two versions and permitted on three. The container agrees with the floor rather than the classifiers, defaulting its base to a Python 3.11 slim image on Debian trixie.

For an organisation standardising on a newer interpreter, that gap is the thing to check, because pip will not stop you and the documentation will not either. There is no upper bound in the metadata, so the failure mode is a runtime incompatibility discovered during a Superset upgrade rather than an install error on day one.

## apache-superset-core is intentionally unbounded, and one transitive dependency was lost

The dependency list carries two comments that read like incident reports, and both change how you should install it. The first is attached to the core package itself.

```toml
"apache-superset-core"
```

The comment above it says there are no bounds for that package until there is a stable version. So a fresh `pip install apache-superset` takes whatever the core package currently is, which is a deliberate acceptance of breakage in exchange for shipping the extracted core as a dependency rather than vendoring it.

The second comment is longer and describes something that actually went wrong. `cachetools` is used directly by the AWS IAM database engine spec, through a TTL cache. It used to arrive transitively through `google-auth`, but version 2.53 and later of that package dropped it, so Superset now declares `cachetools` explicitly to keep a fresh install working without the base extra. The lesson for an operator is narrow and useful: the AWS IAM engine spec is why that dependency exists, and a build that fails on a missing cache module during an unrelated upgrade is this exact dependency, not a broken install of your own.

## The default image builds without translations unless you pass an argument

The Dockerfile is a multi-stage build that starts on the Node side, because the static assets are the slow part. A Node 24 slim image on trixie is the stage that builds the frontend, with a build command that can be overridden and a development flag that skips the frontend build entirely when set.

The one that matters for a non-English deployment is a build argument, declared with a default of false and described as including translations in the final build.

```bash
ARG BUILD_TRANSLATIONS="false"
```

An image built with the defaults therefore contains the English interface only, and the readme never says so. Getting a translated interface means building the image yourself with that argument set, which is a real fork in the deployment path rather than a runtime setting, because translations are compiled into the static assets. The same applies to the build platform argument, which defaults to amd64 and exists so one Dockerfile can produce images for other architectures.

For comparison, the lighter Python-side base is pinned by its own argument to a 3.11 slim image on the same Debian release, so the Python and Node sides of the build are versioned in different places and can drift apart without anything failing.

## Database support means a Python driver and a SQLAlchemy dialect, not a code path

The claim about databases is precise, and the precision is the useful part. Superset can query any SQL speaking datastore or data engine that has two things: a Python DB-API driver and a SQLAlchemy dialect. Presto, Trino and Athena are given as examples, and the list in the readme runs to dozens of engines, including Redshift, Athena, DynamoDB, Apache Doris, Drill, Druid, Hive, Impala, Kylin, Pinot, Solr, Spark SQL, Aurora MySQL and PostgreSQL through their data APIs, Azure Data Explorer, Synapse, ClickHouse, Cloudflare D1, CockroachDB, Couchbase, CrateDB, Databend and Databricks.

The list is not maintained by hand. It sits between comment markers in the readme, which is the signature of a block generated for the docs site, so the repository copy is a copy and the documentation site is the source. That matters when a driver is deprecated: support here means a maintained driver plus a dialect, not a promise from the Superset team, and the two can diverge quietly.

The readme also names a caching layer as configurable, intended to ease load on the source database, and a lightweight semantic layer for defining custom dimensions and metrics. Those are the two features that decide whether a dashboard is fast, and both are configuration work rather than defaults.

## The newest release tags are Helm chart versions, and the tree has been split into packages

The three most recent releases on this repository are all chart releases: superset-helm-chart-0.22.8 on 2026-09-09, 0.22.7 on 2026-09-05 and 0.22.6 on 2026-08-13. The last push to master was 2026-09-25. So the tag with the highest number on the releases page is a deployment chart, not the application, and a script that resolves the latest release to install Superset will resolve a chart instead. There is a `helm/` directory in the tree for that reason.

The repository layout shows the other direction of travel. Alongside the `superset` package sit `superset-core`, `superset-frontend`, `superset-websocket`, `superset-embedded-sdk` and `superset-extensions-cli`, so the parts most likely to be built on rather than modified have been pulled out, and the developer guide points at a REST API and an extension framework. There is also a `.gitmodules` file, so parts of the build come from submodules.

Around that sit the files a large project accumulates: `INSTALL.md` and `UPDATING.md` at the root, a `RELEASING/` directory, `ASF/` and `RESOURCES/`, a pylint configuration, a coverage configuration, pre-commit hooks, and security tooling in the form of a grype configuration, a fossa configuration and a security policy. Agent instructions are present too, as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` and `GPT.md` with a `.claude/` and a `.cursor/` directory.

## Conclusion

Superset is a defensible choice when analysts need to build charts and dashboards over many SQL engines without a commercial licence, and the database support claim is real because it rests on drivers rather than on per-engine code. Before deploying, read INSTALL.md and UPDATING.md rather than the compose file, back up the two named volumes the compose file mounts, and build with translations enabled if your users are not English speakers. Pin the application version explicitly, because the newest release tags on the repository are Helm chart versions.

## FAQ

### How do I install Superset?

The readme points to INSTALL.md at the repository root and to the Administrator Guide, which covers installation, configuration, security, scaling and database drivers. For containers there are four compose files and two Dockerfiles, and the compose file states that it is not supported for production environments.

### How do I use Superset dashboards?

The User Guide is the document for analysts and business users, covering exploring data, building charts, creating dashboards and connecting databases. The readme describes a no-code interface for building charts, a web based SQL editor, and a semantic layer for defining custom dimensions and metrics.

### How do I use the Superset API?

The Developer Guide covers building on the REST API and the extension framework, and the feature list includes an API for programmatic customization. The tree also holds an embedded SDK and an extensions CLI, which are the intended seams for building on top of Superset rather than forking it.

### Is Superset available as a desktop or mobile app?

Nothing in the readme describes a separate application. Superset is described as a web based business intelligence application, reached through a browser, and the distribution routes it documents are the Python package, the container images and the Helm chart.

### How do I install Superset on Ubuntu?

The readme gives no distribution package command. It directs installation to INSTALL.md and the Administrator Guide, and for a container deployment the compose route starts from the repository's docker folder with its own environment file, while pip installs the `apache_superset` distribution, which requires Python 3.11 or newer.

## Sources

- [Official documentation](https://superset.apache.org/)
- [Official README](https://github.com/apache/superset#readme)
- [Project repository](https://github.com/apache/superset)
- [Release notes](https://github.com/apache/superset/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apache-superset