This article explains how to set up a local development environment using Supabase CLI on macOS.

What is Supabase CLI?

Supabase CLI is a command-line tool that enables local Supabase development. It’s used for starting local databases, managing migrations, generating types, and more.

Developing locally allows you to safely develop and test without affecting your production environment.

Prerequisites

To use Supabase CLI, you need the following:

• macOS
• Homebrew: Package manager
• Docker Desktop: Supabase local environment runs in Docker containers

Setting Up Docker Desktop

Supabase CLI launches the local environment in Docker containers, so Docker Desktop must be installed and configured beforehand.

Installation

Download and install the macOS version from the Docker Desktop official website.

Alternatively, you can install it via Homebrew.

brew install --cask docker

Verification

After installation, launch Docker Desktop and verify it’s working in the terminal.

docker --version
# Docker version 27.x.x, build xxxxxxx
 
docker ps
# CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES

If docker ps runs without errors, Docker is working correctly.

Installing Supabase CLI

On macOS, install using Homebrew.

Note: Global installation via npm (npm install -g supabase) is not supported. Please use Homebrew.

# Install Supabase CLI
brew install supabase/tap/supabase
 
# Check version
supabase --version

Updating

To update Supabase CLI to the latest version, run the following command.

brew upgrade supabase

Setting Up the Local Environment

1. Initialize the Project

Initialize Supabase in your project directory.

# Navigate to your project directory
cd your-project
 
# Initialize Supabase project
supabase init

Running supabase init generates a supabase/ folder. This folder can be included in version control.

2. Start the Local Environment

Start local Supabase with the following command.

supabase start

The first startup takes several minutes as Docker images need to be downloaded.

Once startup is complete, information like the following will be displayed.

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:postgres@127.0.0.1:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324

3. Accessing Supabase Studio

Access http://127.0.0.1:54323 in your browser to open Supabase Studio. This is Supabase’s graphical interface where you can create tables, view data, execute SQL, and more.

4. Stopping the Local Environment

When you’re done developing, stop the local environment with the following command.

supabase stop

To stop while preserving data, simply run supabase stop. To reset data when stopping, use the --no-backup option.

# Stop and reset data
supabase stop --no-backup

Common Commands

Troubleshooting

supabase: command not found

Cause: Supabase CLI is not installed, or PATH is not configured

Solution:

# Reinstall with Homebrew
brew install supabase/tap/supabase
 
# Check PATH
which supabase

Docker daemon is not running

Cause: Docker is not running

Solution:

# Launch Docker Desktop
open /Applications/Docker.app
 
# Verify Docker is running
docker ps

Error: Cannot connect to the Docker daemon

Cause: Docker is not functioning properly

Solution:

# Restart Docker Desktop
# Select "Restart" from the Docker icon in the menu bar
 
# Verify again
docker ps
supabase start

Port is already in use

Cause: Another process is using the same port

Solution:

# Check which process is using the port (e.g., 54321)
lsof -i :54321
 
# Either terminate the process or change the port in Supabase settings

You can customize port numbers in supabase/config.toml.

Conclusion

With Supabase CLI, you can run the complete Supabase stack locally. Being able to test production-equivalent features locally significantly improves development efficiency.

With just Docker Desktop and Homebrew, setup can be completed in minutes, so give it a try.

For more details, refer to the Supabase CLI official documentation.

That’s all from the Gemba, where we set up a Supabase local environment with Supabase CLI.