Installing the Supabase CLI

Step-by-step guide to installing the Supabase CLI on any platform

The Supabase CLI is available for macOS, Windows, and Linux. Choose your installation method based on your operating system and preferences.

Prerequisites

Before installing the Supabase CLI, ensure you have:

• Docker Desktop (or compatible container runtime) - Required for running Supabase locally
• Node.js 20+ (if using npm/npx method)

While the CLI can be installed via npm, it requires Node.js 20 or later. Older versions like Node.js 16 are not supported.

Installation Methods

macOS

Using Homebrew (Recommended)

The easiest way to install the CLI on macOS is using Homebrew:

brew install supabase/tap/supabase

Verify Installation

After installation, verify the CLI is working:

supabase --version

Updating

To update to the latest version:

brew upgrade supabase

Windows

Using Scoop (Recommended)

Install the CLI using Scoop:

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Verify Installation

After installation, verify the CLI is working:

supabase --version

Updating

To update to the latest version:

scoop update supabase

Linux

Using Homebrew

Install via Homebrew on Linux:

brew install supabase/tap/supabase

To update:

brew upgrade supabase

Using Linux Packages

Download the appropriate package from the CLI releases page:

Alpine Linux (.apk)

# Download the .apk file from releases
sudo apk add --allow-untrusted supabase_<version>_linux_amd64.apk

Debian/Ubuntu (.deb)

# Download the .deb file from releases
sudo dpkg -i supabase_<version>_linux_amd64.deb

Fedora/RHEL (.rpm)

# Download the .rpm file from releases
sudo rpm -i supabase_<version>_linux_amd64.rpm

Updating Linux Packages

To update, download the latest package and reinstall using the same command.

npm/npx

Using npx (No Installation)

Run the CLI without installing by prefixing commands with npx:

npx supabase --help

The Supabase CLI requires Node.js 20 or later when run via npx or npm. Older Node.js versions are not supported.

Install as Dev Dependency

Install the CLI as a development dependency in your project:

npm install supabase --save-dev

Then use it via npm scripts:

package.json

{
  "scripts": {
    "supabase": "supabase",
    "db:start": "supabase start",
    "db:stop": "supabase stop"
  }
}

Updating

To update the CLI:

npm update supabase --save-dev

Installing Docker

The Supabase CLI uses Docker containers to run the local development stack. Install Docker Desktop for your platform:

macOS

Docker Desktop for macOS

1. Download Docker Desktop for Mac
2. Install and start Docker Desktop
3. Configure Docker settings:

Recommended Settings:

• ✅ Use integrated virtualization framework
• ✅ Enable VirtioFS
• ✅ Use osxfs (legacy) file sharing

Alternative Container Runtimes

You can also use:

• OrbStack - Lightweight Docker alternative for macOS
• Colima - Container runtime for macOS
• Rancher Desktop - Open-source Docker alternative

Windows

Docker Desktop for Windows

1. Download Docker Desktop for Windows
2. Install and start Docker Desktop
3. Configure Docker settings:

Recommended Settings:

• ✅ Use the WSL 2 based engine
• ✅ Expose daemon on tcp://localhost:2375
• ✅ Add /etc/hosts file entries

Alternative Container Runtimes

• Rancher Desktop
• Podman

Linux

Docker Engine for Linux

Install Docker Engine following the official Linux installation guide.

Alternative Container Runtimes

• Podman - Daemonless container engine
• Rancher Desktop

Post-Installation

Verify Docker Installation

Verify Docker is running:

docker --version
docker ps

Verify Supabase CLI Installation

Check that the CLI is properly installed:

supabase --version

You should see output like:

supabase 1.x.x

First-Time Setup

The first time you run supabase start, the CLI will download all necessary Docker images. This may take several minutes:

supabase init
supabase start

The initial download includes images for PostgreSQL, PostgREST, GoTrue, Kong, Realtime, Storage, and other services - approximately 2-3 GB total.

Updating the CLI

When to Update

Check for new releases on the Supabase CLI releases page. We recommend updating regularly to get the latest features and bug fixes.

Update Process

Update the CLI using the same method you used to install it:

macOS (Homebrew)

brew upgrade supabase

Windows (Scoop)

scoop update supabase

Linux (Homebrew)

brew upgrade supabase

npm

npm update supabase --save-dev

Important: Stop Containers Before Upgrading

Before upgrading, stop your local Supabase containers and delete data volumes to ensure services can apply new migrations cleanly.

Backup and stop running containers:

# Save your schema changes
supabase db diff -f my_schema

# Save your data
supabase db dump --local --data-only > supabase/seed.sql

# Stop and remove containers (--no-backup deletes volumes)
supabase stop --no-backup

After upgrading, restart:

supabase start

Troubleshooting

Command not found: supabase

macOS/Linux:

• Ensure Homebrew’s bin directory is in your PATH
• Restart your terminal
• Try running with full path: /opt/homebrew/bin/supabase

Windows:

• Ensure Scoop’s shims directory is in your PATH
• Restart PowerShell/Command Prompt

Docker not running

Error: Cannot connect to the Docker daemon

Solution:

• Start Docker Desktop
• Verify Docker is running: docker ps
• On Linux, ensure your user is in the docker group: sudo usermod -aG docker $USER

Node.js version too old

Error when using npx: The Supabase CLI requires Node.js 20 or later

Solution:

• Update Node.js to version 20 or later
• Use a different installation method (Homebrew, Scoop)
• Use a Node version manager like nvm

Port already in use

Error: Port 54321 is already in use

Solution:

• Stop any services using ports 54321-54324
• Or configure custom ports in supabase/config.toml

Next Steps

Local Development

Set up your local development environment

CLI Reference

Explore all CLI commands

Migrations

Learn database migration workflows

GitHub Actions

Set up CI/CD with GitHub Actions