How to Set Up Apache Superset for Analytics

Apache Superset is an open source BI platform backed by the Apache Software Foundation. It runs on your own infrastructure, connects to virtually any SQL database, and lets non-technical users build charts and dashboards through a point-and-click interface. This guide walks through installing Superset with Docker Compose, connecting a database, and publishing your first dashboard. If you do not yet have a database to connect, skip to the end for a shortcut.

Prerequisites

You need Docker Desktop (version 20 or later) and Git installed on your machine. Superset officially supports Linux and macOS. Windows users can run it through WSL2. Check your versions before starting:

docker --version
docker compose version
git --version

Each command should return a version number. If Docker Compose is missing, install it through Docker Desktop or follow the standalone guide at docs.docker.com/compose/install.

You do not need Python or Node installed locally. Superset runs entirely inside Docker containers.

Step 1: Clone the Repository and Pin to a Release

git clone https://github.com/apache/superset.git
cd superset
git checkout tags/4.1.2

Always pin to a release tag rather than running off the main branch. The main branch is active development and may be in a broken state. As of April 2026, version 4.1.x is the current stable release. Check the GitHub releases page for the latest tag before running this command, as newer patches are released regularly.

Step 2: Start Superset with Docker Compose

Superset ships with a Docker Compose file designed for local evaluation:

docker compose -f docker-compose-image-tag.yml up

This pulls the Superset container image and starts five services: the Superset application server, a PostgreSQL metadata database, Redis for caching, a Celery worker for background tasks, and a Celery beat scheduler for scheduled queries. The first pull takes 3 to 5 minutes depending on your connection speed. Subsequent starts use cached images and take under 30 seconds.

When startup completes, you will see log output from the superset_init container confirming that example data was loaded. Open http://localhost:8088 and log in with the default credentials: username admin, password admin. Change the admin password immediately after your first login under Settings > Security > List Users.

Step 3: Connect Your First Database

Superset does not store or process your data directly. It connects to a database that already contains your data and issues SQL queries against it at query time. To connect a source, go to Settings > Database Connections > Add Database.

Select your database type from the dropdown. Superset supports PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, ClickHouse, DuckDB, and more than 40 others. For PostgreSQL, enter the connection string in this format:

postgresql://username:password@host:port/database_name

Click Test Connection before saving. If the test passes, click Add. Superset stores only connection metadata, not your data.

For BigQuery, upload a service account JSON key file instead of entering a connection string. The service account needs at least the BigQuery Data Viewer and BigQuery Job User roles on the target project.

For Snowflake, use the format snowflake://user:password@account/database/schema?warehouse=WAREHOUSE_NAME. The account identifier follows the format orgname-accountname from your Snowflake URL.

Step 4: Register a Dataset

A dataset in Superset is a saved reference to a table, view, or custom SQL query. Before building a chart, register the data you want to visualize. Go to Datasets > Add Dataset. Select the database you connected, then pick the schema and table from the dropdowns. Click Save.

Superset reads column names and data types from the table schema and stores them in its metadata database. This takes a few seconds for most tables. For exploratory work, use the SQL Lab (top menu > SQL > SQL Lab) to write and test a query first, then save it as a virtual dataset.

Step 5: Build Your First Chart

Open the Datasets tab, find your dataset, and click the chart icon on the right side. This opens the Explore view. The chart builder has three sections: chart type selector on the left, configuration panel in the center, and a live preview on the right.

Select a chart type based on your data shape. For time-series data, use Time-Series Bar Chart or Line Chart. For category breakdowns, use Bar Chart. For single KPIs, use Big Number. For geographic data, use the Map chart type.

In the Metrics field, drag a numeric column or write a custom aggregation such as SUM(revenue) or COUNT(DISTINCT user_id). Set a Time Column if your data has timestamps. Click Update Chart to render a preview. The query time appears below the chart, which helps you identify slow aggregations before publishing the dashboard.

Save the chart using the button in the top right. Use descriptive names like "Weekly Active Users by Country" rather than "user_count chart."

Step 6: Build and Share a Dashboard

Dashboards collect multiple charts into a single view. Go to Dashboards > New Dashboard. Enter a title in the top bar, then click Edit Dashboard.

A panel on the right shows your saved charts. Drag charts from the panel onto the canvas. Use the grid handles to resize each chart. Superset uses a column-based grid so charts snap into alignment automatically.

Once arranged, click Save. To share a dashboard with a team member, go to the dashboard settings and assign the Viewer role to their Superset user account. For external embedding, Superset provides an Embedded SDK that generates signed tokens for iframe embedding inside your own application.

Row-Level Security

Once a team is using the same Superset instance, restricting which rows different users see is a common need. Go to Settings > Row Level Security to create filters that apply a SQL WHERE clause per role. For example, regional managers see only rows where region = 'APAC' while global admins see all rows.

Row-level security at the BI layer means you can grant dashboard access without handing out direct database credentials. Access is defined in one place and applies to every chart connected to that dataset. This is one of Superset's practical advantages over sharing static spreadsheet exports.

Enabling Query Caching

Superset includes a Redis-backed query cache. When a user loads a dashboard, Superset checks whether the query result is already in cache. If it is, it skips the database round-trip and returns the cached result. The default cache TTL is 86,400 seconds (24 hours).

To configure caching, open superset_config.py and set CACHE_CONFIG. The Docker Compose setup already includes Redis, so caching works out of the box for local deployments. For production, point the Redis config at your managed Redis instance. Teams with high-traffic dashboards see a 60 to 80 percent reduction in database query volume after enabling caching.

Deploying to Production

The Docker Compose setup is for local evaluation only. It stores metadata in a container-local PostgreSQL instance that is not backed up and resets on container teardown. For production, the Superset team recommends deploying with Kubernetes using the official Helm chart at github.com/apache/superset/tree/master/helm/superset.

For smaller teams without Kubernetes, the commercial managed service Preset.io handles upgrades, backups, and scaling. Preset was founded by the original creator of Superset and runs a hosted version with a per-seat pricing model.

Practical Summary

Apache Superset takes about 15 minutes to get running locally with Docker Compose. The core workflow is: connect a database, register datasets from tables or saved SQL queries, build charts in the Explore view, and assemble charts into dashboards. Row-level security and query caching handle the two most common production requirements. The key constraint to understand upfront is that Superset queries your existing database at runtime. If you do not have a database set up yet, you need one before Superset is useful. For ad hoc file-based analysis where you want to upload a CSV or spreadsheet and get answers immediately, a tool like VSLZ handles that without any server setup.