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

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

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.

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#

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

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)

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

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)"

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

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

psql --version
# psql (PostgreSQL) 16.x

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

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

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.

When pg_dump (and other tools) are not found even after installing the client#

You’ve followed the install steps above and psql --version works, but your application or tooling still fails with:

pg_dump executable was not found.
install postgresql client tools or configure 'pgsql.pgbinarydirs'.

This error is specific to applications that shell out to PostgreSQL binaries — most commonly Visual Studio Code with the PostgreSQL extension, or Node.js ORM tooling like Prisma, Drizzle, or Knex when they try to call pg_dump for backup or introspection tasks. The root cause is not that the binaries are missing; it is that the calling process cannot locate them because the PATH it inherits does not include the installation directory.

On macOS, the Homebrew postgresql-client formula installs binaries into a versioned, architecture-specific path (/opt/homebrew/opt/postgresql-client/bin on Apple Silicon, /usr/local/opt/postgresql-client/bin on Intel). GUI applications started from Finder, Spotlight, or the Dock do not read your shell's ~/.zshrc or ~/.bashrc, so they launch with a minimal PATH that omits those directories entirely.

The fix: configure pgsql.pgbinarydirs#

VS Code’s PostgreSQL extension (and similar tools) accepts an explicit binary directory configuration. Open VS Code Settings (JSON), and add the path that matches your architecture:

{
  "pgsql.pgbinarydirs": ["/opt/homebrew/opt/postgresql-client/bin"]
}

For Intel Macs, use "/usr/local/opt/postgresql-client/bin". For Linux installations via apt or dnf, psql typically lands in /usr/bin/, which is already on the default PATH for all processes — if you see this error on Linux, confirm the binary actually exists with which pg_dump and ensure the package postgresql-client (not just postgresql) is installed.

Why this happens even when psql works in your terminal#

Your terminal is started from a shell that sources ~/.zshrc, which Homebrew’s installer modifies with the appropriate PATH entry. VS Code (and other GUI apps) are not launched from that shell; they inherit the system’s launchd environment, which has a bare-minimum PATH: typically /usr/bin:/bin:/usr/sbin:/sbin. The Homebrew prefix is absent. The pgsql.pgbinarydirs setting tells the extension exactly where to look, bypassing PATH entirely.

If you are using a different tool that throws the same error but has no equivalent config key, launch it from the terminal instead (code . from a shell that has the correct PATH, or open -a "Visual Studio Code"). If the tool is a Node.js script or CLI, ensure the process that spawns it (a terminal, a build script, or a supervisor) has loaded the full shell environment. For more on debugging connection issues once the tools are found, see the Peer Authentication Failed fix.

Related Articles#

• How to Show Tables in PostgreSQL (psql + Supabase)
• PostgreSQL DESCRIBE TABLE: The psql backslash-d Equivalent
• Fix: Peer Authentication Failed for User "postgres"
• How to Switch Database in psql
• PostgreSQL Slow Queries Fix
• Debugging Supabase RLS Issues
• Fix PostgreSQL Server Won't Start on Mac OS X (2026)