This guide walks you through setting up Supabase Studio locally so you can develop, test, and explore your Supabase project right on your own machine, no internet required.

We'll cover two approaches: running the full local Supabase stack (the easiest way), and running the Studio frontend from source for contributors. Let's get started!

Why Run Supabase Locally?

Before diving in, here's why local development matters:

  • Offline development - work without an internet connection
  • Faster iteration - no network latency for database queries
  • Safe experimentation - break things without affecting production
  • Schema migrations - capture database changes as migration files you can version control
  • Cost savings - no usage charges while developing locally

Prerequisites

Make sure you have these tools installed before proceeding:

1. Docker Desktop (or alternative)

Supabase runs its services (Postgres, Auth, Storage, etc.) in Docker containers. You need one of these:

  • Docker Desktop - the most common choice (macOS, Windows, Linux)
  • OrbStack - a lightweight, fast alternative (macOS)
  • Rancher Desktop - open-source option (macOS, Windows, Linux)
  • Podman - daemonless container engine (macOS, Windows, Linux)
  • colima - minimal setup for macOS

Make sure your container runtime is running before proceeding.

2. Node.js (v20 or later)

The Supabase CLI requires Node.js 20+. Older versions (16, 18) are not supported and will fail.

node -v  # Should show v20.x.x or higher

Download from nodejs.org if needed (grab the LTS version).

3. Git

You'll need Git to clone the Supabase repository.

git --version

Get it from git-scm.com/downloads if you don't have it.

4. Supabase CLI

The CLI is what orchestrates your entire local Supabase environment. Install it using one of these methods:

Via npm (recommended):

npm install -g supabase

Via npx (no install needed):

npx supabase <command>

Via Homebrew (macOS/Linux):

brew install supabase/tap/supabase

Verify the installation:

supabase --version

5. pnpm

The Supabase monorepo uses pnpm as its package manager.

npm install -g pnpm

This is the easiest way to get Supabase Studio running locally. The CLI spins up all services including Studio automatically.

Step 1: Initialize Your Project

Create a new directory for your project (or navigate to an existing one) and initialize Supabase:

mkdir my-project && cd my-project
supabase init

This creates a supabase/ directory with a config.toml file where you can customize your local setup.

Step 2: Start the Local Stack

Make sure Docker is running, then:

supabase start

The first run takes a few minutes as it downloads the required Docker images. Once complete, you'll see output like:

Started supabase local development setup.

         API URL: http://127.0.0.1:54321
     GraphQL URL: http://127.0.0.1:54321/graphql/v1
  S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
          DB URL: postgresql://postgres:[email protected]:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324
        anon key: eyJ...
service_role key: eyJ...

Step 3: Open Studio

Open your browser and go to:

http://127.0.0.1:54323

That's it! You now have the full Supabase Studio dashboard running locally, connected to a local Postgres database. You can create tables, manage users, write SQL, and more.

Stopping the Stack

supabase stop        # Stops services, preserves data
supabase stop --no-backup  # Stops and resets all data

Approach 2: Running Studio from Source (For Contributors)

If you want to contribute to Supabase Studio or customize it, you can run the frontend from the source code.

Step 1: Clone the Repository

git clone --depth 1 https://github.com/supabase/supabase.git

The --depth 1 flag does a shallow clone, much faster than downloading the full history.

Step 2: Navigate to Studio

cd supabase/apps/studio

Step 3: Set Up Environment Variables

cp .env.example .env

The defaults work for local development. If you're running a self-hosted Docker setup, update these values in .env:

  • POSTGRES_PASSWORD
  • SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_KEY

You can optionally set DEFAULT_ORGANIZATION_NAME and DEFAULT_PROJECT_NAME to customize the dashboard.

Step 4: Install Dependencies

pnpm install

This reads package.json and pnpm-lock.yaml to download all required packages. It may take a few minutes.

Step 5: Start the Backend

Open a terminal and start the local Supabase backend:

supabase start

Keep this terminal open, the backend needs to stay running.

Step 6: Start Studio Dev Server

In a new terminal, from the supabase/apps/studio directory:

pnpm dev

The Studio dev server typically starts on http://localhost:8082.

Keeping Up to Date

The Studio codebase is actively developed. Pull updates regularly:

git pull origin master
pnpm install

Working with Schema Migrations

One of the biggest advantages of local development is capturing your database changes as migration files:

  1. Make changes in Studio (create tables, add columns, etc.)
  2. Generate a migration from those changes: 
    supabase db diff -f my_migration_name
  3. Apply migrations to your hosted project: 
    supabase db push

This gives you version-controlled, repeatable database changes, essential for team collaboration and CI/CD pipelines.

Troubleshooting

Here are solutions to common issues:

Docker not running: The most common error. Make sure Docker Desktop (or your alternative) is running before you execute supabase start.

Port conflicts: If you see "port already in use" errors, another service is using the same ports. You can change ports in supabase/config.toml:

[api]
port = 54321

[studio]
port = 54323

Node version too old: The CLI requires Node.js 20+. Check with node -v and upgrade if needed.

Stale containers: If things get weird after an update, reset everything:

supabase stop
supabase start

Out of disk space: Docker images can accumulate. Clean up with:

docker system prune

FAQs

General Supabase Questions

Q: What exactly is Supabase? A: Supabase is an open-source Backend as a Service (BaaS) built on top of PostgreSQL. It provides authentication, a real-time database, file storage, edge functions, and a dashboard (Studio) to manage it all. Think of it as an open-source Firebase alternative.

Q: Is Supabase free? A: Yes! Supabase has a generous free tier for hosted projects, and running it locally is completely free (just uses your computer's resources).

Q: What frameworks work with Supabase? A: Supabase provides client libraries for JavaScript/TypeScript, Flutter, Swift, Kotlin, and Python. It works with any framework: React, Next.js, Vue, Svelte, React Native, and more.

Local Development Questions

Q: What's the difference between Approach 1 and Approach 2? A: Approach 1 (supabase start) runs the full pre-built stack including Studio, perfect for app development. Approach 2 runs the Studio frontend from source code, useful if you want to contribute to Supabase itself or customize the dashboard.

Q: Will my local data show up on supabase.com? A: No. Your local environment is completely isolated. Local data stays local, and your hosted project's data stays online. You can sync schema changes (not data) using supabase db push.

Q: Do I really need Docker? A: Yes. The Supabase CLI uses Docker containers to run PostgreSQL, Auth, Storage, and other services. Without a container runtime, the local stack won't start.

Q: How much disk space does it need? A: The Docker images total around 2-3 GB on first download. After that, subsequent starts are fast since the images are cached.

Q: Can I use a different database port? A: Yes! Edit supabase/config.toml in your project to change any port. Run supabase stop then supabase start for changes to take effect.

Happy building!