supabase-podman-mac-setup.md

🧪 Running Supabase Locally with Podman on macOS (M1/M2)

This guide walks you through running the full Supabase stack without Docker Desktop, using Podman and the Supabase CLI.

✅ Why Use Podman?

• Lightweight alternative to Docker
• Works great on Apple Silicon
• No Docker Desktop licensing constraints

---

🛠 One-Time Setup

1. Install Required Tools

brew install podman
brew install supabase/tap/supabase

2. Create and Start the Podman VM

podman machine init
podman machine start

Verify it’s running:

podman machine list

3. Set Up Docker API Compatibility

After starting the Podman machine, it will print a socket path like this:

export DOCKER_HOST='unix:///var/folders/.../podman-machine-default-api.sock'

Copy and paste that line into your shell or add the following to your ~/.zshrc:

function podman_ready() {
  if ! podman machine info &>/dev/null; then
    podman machine start
  fi
  export DOCKER_HOST="unix:///var/folders/rs/76gmr0xs0fv_1s3qs1dnh3sw0000gn/T/podman/podman-machine-default-api.sock"
}
alias supabase-start="podman_ready && supabase start"
alias supabase-stop="supabase stop && podman machine stop"

Then reload:

source ~/.zshrc

---

🚀 Running Supabase

To start:

supabase-start

To stop:

supabase-stop

Studio (UI) → http://localhost:54323 API Gateway → http://localhost:54321

---

🔍 Debugging

See container logs:

podman logs supabase_db

Check service health:

supabase status

---

🖥 Optional: Use Podman Desktop

Podman Desktop is a free GUI to view containers, logs, and metrics. Works great for inspecting Supabase services visually.

---

📎 Related Links

• Supabase CLI: https://supabase.com/docs/guides/local-development
• Podman: https://podman.io
• Podman Desktop: https://podman.io/podman-desktop/