DEV Community

Cover image for Fix: psql: command not found (Install PostgreSQL Client)
Mahdi BEN RHOUMA
Mahdi BEN RHOUMA

Posted on Originally published at iloveblogs.blog

Fix: psql: command not found (Install PostgreSQL Client)

#postgres #psql #install #troubleshooting

You open a terminal — maybe to debug a Supabase connection, run a migration, or follow a tutorial — type psql and the shell answers:

$ psql
bash: psql: command not found
Enter fullscreen mode Exit fullscreen mode

On Windows PowerShell it is the same error in different words:

PS C:\> psql
psql : The term 'psql' is not recognized as the name of a cmdlet, function, script file, or operable program.
Enter fullscreen mode Exit fullscreen mode

The Stack Overflow canonical (Q33235968, ~700k views) is short: the PostgreSQL client is not installed, or installed but not on your shell's PATH. The two are easy to confuse — psql is a separate package on Linux and a separate Homebrew formula on macOS. Here are the exact fixes per platform.

Quick fix — install the right package

Platform Command What it installs
Debian / Ubuntu sudo apt install postgresql-client psql + libpq + pg_isready + pg_dump
Fedora / RHEL sudo dnf install postgresql client + server
macOS (Intel) brew install postgresql-client psql in /usr/local/opt/postgresql-client/bin/psql
macOS (Apple Silicon) brew install postgresql-client psql in /opt/homebrew/opt/postgresql-client/bin/psql
Windows (Chocolatey) choco install postgresql full installer, adds bin to PATH
Windows (manual) EDB installer from postgresql.org full installer, adds bin to PATH
Docker (any host) docker exec -it <container> psql -U postgres psql already inside the postgres image

After installing, open a new terminal and run psql --version. If you see a version string, the binary is on PATH and ready.

Linux — Debian / Ubuntu / Fedora

postgresql-client (Debian family) or postgresql (RHEL family) gives you psql, pg_dump, pg_isready, and createdb — every CLI you need to talk to a Postgres server, even if the server itself runs elsewhere (Supabase, Neon, RDS, a Docker container).

# Debian / Ubuntu
sudo apt update
sudo apt install -y postgresql-client

# Verify
psql --version
# psql (PostgreSQL) 16.x
Enter fullscreen mode Exit fullscreen mode

If you want a specific major version to match a server (16.4 server ↔ 16.x client), install postgresql-client-16 instead. Mixing majors usually works but the client emits a server-version-mismatch notice on connect — annoying, not fatal.

macOS — Homebrew (Intel and Apple Silicon)

The trap on macOS is brew install libpq. The libpq formula installs the C client library only — it does not ship the psql binary since 2022. Running psql after brew install libpq still gives "command not found".

brew install postgresql-client
which psql
# /opt/homebrew/opt/postgresql-client/bin/psql  (Apple Silicon)
# /usr/local/opt/postgresql-client/bin/psql      (Intel)
Enter fullscreen mode Exit fullscreen mode

If you want the library but also psql, you have two choices:

# Option A: install the full client (recommended)
brew install postgresql-client

# Option B: keep libpq and force-link psql into /opt/homebrew/bin
brew install libpq
brew link --force libpq
Enter fullscreen mode Exit fullscreen mode

For Apple Silicon Macs, Homebrew lives at /opt/homebrew — make sure your ~/.zshrc (zsh is the default on macOS 10.15+) contains the Homebrew path:

# ~/.zshrc — only needed if Homebrew did not add it
eval "$(/opt/homebrew/bin/brew shellenv)"
Enter fullscreen mode Exit fullscreen mode

After editing ~/.zshrc, source ~/.zshrc or open a new terminal.

Windows — Chocolatey or EDB installer

There are two routes on Windows. Both work; the EDB installer is the official one.

Option A — Chocolatey (fast, scripted) 

choco install postgresql -y
# psql lands in C:\Program Files\PostgreSQL\<version>\bin
# Chocolatey adds it to PATH automatically
Enter fullscreen mode Exit fullscreen mode

Close and reopen PowerShell so the new PATH loads. Then:

psql --version
# psql (PostgreSQL) 16.x
Enter fullscreen mode Exit fullscreen mode

Option B — EDB installer (official)

Download from postgresql.org/download/windows and run the installer. At the component-selection step, postgreSQL client must stay checked — the server component is optional if you only want psql. The installer adds C:\Program Files\PostgreSQL\<major>\bin to your user PATH and drops a SQL Shell (psql) shortcut in the Start Menu. That shortcut opens a psql session with prompts for server, database, user, and password — works even if your PATH did not update.

Docker — psql already inside the container

If your database runs in Docker (the official postgres image, or a Supabase local stack via supabase start), do not install psql locally just for one-off queries. The image already has it.

# Postgres container started with docker compose
docker compose up -d postgres

# Find the running container name or use the service name
docker exec -it <container_name_or_id> psql -U postgres
# or, with docker compose:
docker compose exec postgres psql -U postgres
Enter fullscreen mode Exit fullscreen mode

For Supabase local dev:

supabase start
# ... wait for "API URL", "Studio URL", "DB URL" ...

# DB URL is postgresql://postgres:postgres@localhost:54322/postgres
# The studio runs at http://127.0.0.1:54323 (separate from the DB port)
docker exec -it supabase_db_<project-ref> psql -U postgres
Enter fullscreen mode Exit fullscreen mode

If the image is bare (postgres:16-alpine with no entrypoint overridden), psql is at /usr/local/bin/psql — the exec path above lands you in a shell where you can run it directly.

Common mistakes

  • Installed the server, forgot the client. On Debian postgresql (server) and postgresql-client (CLI) are separate packages — apt install postgresql does not put psql on your path.
  • brew install libpq and expected psql. libpq is the C library only. Run brew install postgresql-client for the CLI.
  • Wrong PATH on Apple Silicon. psql is at /opt/homebrew/opt/postgresql-client/bin/psql, not /usr/local. Add /opt/homebrew/opt/postgresql-client/bin to PATH or rely on Homebrew's automatic shellenv.
  • PATH edit did not take effect. export PATH=... only updates the current shell. Edit ~/.zshrc, ~/.bashrc, or the Windows Environment Variables dialog, then open a new terminal.
  • Docker container is not running. docker exec fails with Error: No such container — start it first with docker compose up -d <service> or supabase start.
  • Wrong container name. docker ps lists running containers; copy the NAMES column exactly. Names auto-generated by compose use the project prefix.
  • psql is installed but version mismatches the server. psql: server version 15.0, server version 16.4 warning on connect — harmless, ignore it. Upgrade the client if you want it gone.

Official references: PostgreSQL — Client Applications (psql), PostgreSQL — Downloads, Homebrew — postgresql-client formula, Microsoft — Chocolatey postgresql package.

Related Articles

Originally published at https://www.iloveblogs.blog

Top comments (0)