# Dependencies for Building Apache Superset: Complete System and Package Requirements

> Build Apache Superset by meeting system and package requirements. Discover essential dependencies like Bun v1.0+, macOS, Git, GitHub CLI, and Caddy for your superset-sh/superset development.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: how-to-guide
- Published: 2026-03-08

---

**Building Apache Superset from the superset-sh/superset repository requires Bun v1.0+, macOS, Git ≥2.20, GitHub CLI, Caddy, and specific npm packages managed through a TurboRepo monorepo structure.**

The superset-sh/superset project is a Bun-powered monorepo that packages Apache Superset as both a web and desktop application. Understanding the complete dependency chain—from system-level tools to workspace-specific runtime libraries—is essential for successfully compiling the project from source.

## System-Level Requirements for Building Apache Superset

Before installing package dependencies, your development environment must provide several core system tools. These are documented in the repository's [`README.md`](https://github.com/superset-sh/superset/blob/main/README.md) under the "Requirements" section.

### Operating System and Runtime

The build process is optimized for **macOS**. While the codebase may compile on other platforms, Windows and Linux environments remain untested and unsupported according to the project documentation.

**Bun v1.0 or higher** serves as the mandatory JavaScript runtime and package manager. Unlike Node.js-based projects, superset-sh/superset relies on Bun's specific APIs and performance characteristics for both development and production builds.

### Required System Tools

| Tool | Minimum Version | Purpose |
|------|----------------|---------|
| **Git** | ≥ 2.20 | Version control and submodule management |
| **GitHub CLI** (`gh`) | Latest | Required for development scripts and automation workflows |
| **Caddy** | Latest | Reverse-proxy server for Electric SQL streams in development mode |

## Core Build Tooling and Development Dependencies

The root [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json) defines monorepo-wide development dependencies that orchestrate the build process across all workspaces.

```json
{
  "devDependencies": {
    "@biomejs/biome": "2.4.2",
    "dotenv-cli": "^11.0.0",
    "sherif": "^1.10.0",
    "turbo": "^2.8.7"
  }
}

```

**`@biomejs/biome`** provides unified linting and formatting across the codebase, replacing separate ESLint and Prettier configurations. **`turbo`** acts as the monorepo build orchestrator, enabling cached builds and parallel execution across the `apps/*` and `packages/*` workspaces. **`sherif`** manages workspace-wide script consistency, while **`dotenv-cli`** loads environment variables from `.env` files during script execution.

## Workspace-Specific Runtime Dependencies

Each workspace within the monorepo declares its own runtime dependencies. The project structure separates applications (`apps/`) from shared libraries (`packages/`).

### Web Application Dependencies

The `apps/web` workspace contains the Next.js frontend and requires a comprehensive React ecosystem:

- **Framework**: `next`, `react`, `react-dom`
- **Data Fetching**: `@tanstack/react-query`, `@trpc/client`, `@trpc/server`, `@trpc/react-query`
- **UI Components**: `framer-motion`, `lucide-react`, `@superset/ui` (workspace dependency)
- **State Management**: Zustand or similar (implied by package structure)

See [`apps/web/package.json`](https://github.com/superset-sh/superset/blob/main/apps/web/package.json) for the complete dependency tree.

### Desktop Application Dependencies

The `apps/desktop` workspace builds an Electron wrapper around the web application. Key dependencies include:

- **Electron**: Core runtime for desktop packaging
- **Native Modules**: `node-pty` for terminal emulation within the desktop environment
- **Builder**: `electron-builder` for creating distributable installers

The [`apps/desktop/BUILDING.md`](https://github.com/superset-sh/superset/blob/main/apps/desktop/BUILDING.md) file contains specific instructions for handling native module compilation.

### Shared Package Dependencies

The `packages/` directory contains modular libraries consumed by both web and desktop applications:

- **`packages/ui`**: React components built on `tailwindcss`, `class-variance-authority`, and `shadcn/ui` primitives
- **`packages/db`**: Database layer using `drizzle-orm`, `@neondatabase/serverless`, and `postgres` drivers
- **`packages/auth`**: Authentication utilities and providers
- **`packages/trpc`**: tRPC router and procedure definitions shared between client and server
- **`packages/shared`**: Common utilities, types, and constants

## Step-by-Step Build Process Using Apache Superset Dependencies

To build the project from source, execute these commands in sequence:

```bash

# 1. Clone the repository

git clone https://github.com/superset-sh/superset.git
cd superset

# 2. Configure environment variables

cp .env.example .env
echo 'SKIP_ENV_VALIDATION=1' >> .env  # Optional: bypasses strict env validation

# 3. Install all dependencies using Bun

# This installs root devDependencies (@biomejs/biome, turbo, etc.)

# and all workspace dependencies (Next.js, Electron, Drizzle ORM, etc.)

bun install

# 4. Start the development servers

# TurboRepo orchestrates parallel startup of web, desktop, and database services

bun run dev

# 5. Build the desktop application for distribution

# Uses Turbo's filtered build to target only the desktop workspace

bun run build  # Equivalent to: turbo build --filter=@superset/desktop

```

## Summary

Building Apache Superset from the superset-sh/superset repository requires a specific toolchain centered on Bun rather than Node.js. Key takeaways include:

- **System prerequisites**: macOS, Bun v1.0+, Git ≥2.20, GitHub CLI, and Caddy are mandatory for the build process.
- **Monorepo architecture**: The project uses TurboRepo to manage dependencies across `apps/web`, `apps/desktop`, and multiple `packages/*` workspaces.
- **Core tooling**: Root-level devDependencies include `@biomejs/biome` for linting, `turbo` for build orchestration, and `sherif` for script management.
- **Runtime stack**: Web dependencies center on Next.js and React, while the desktop build requires Electron and native modules like `node-pty`.

## Frequently Asked Questions

### What is the minimum Bun version required to build Apache Superset?

The superset-sh/superset repository requires **Bun v1.0 or higher**. This runtime is mandatory because the build scripts and package management rely on Bun-specific APIs and performance characteristics that differ from Node.js.

### Can I build Apache Superset on Windows or Linux?

Currently, **macOS is the only supported operating system** for building from source. While the codebase may theoretically compile on Windows or Linux, these platforms remain untested and unsupported according to the repository's README documentation.

### What is the purpose of Caddy in the build process?

**Caddy serves as a reverse-proxy server** specifically for Electric SQL streams during development mode. It is not required for production builds but is necessary for local development to handle real-time database synchronization features used by the application.

### How do workspace dependencies differ from root dependencies in the monorepo?

**Root dependencies** (defined in the repository's [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json)) are primarily development tools like `turbo`, `@biomejs/biome`, and `sherif` that manage the entire monorepo. **Workspace dependencies** (defined in individual `apps/*/package.json` and `packages/*/package.json` files) are runtime libraries specific to each application or shared package, such as `next` for the web app or `electron` for the desktop app.