psql command not found: install the client or fix PATH

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

$ 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 canonicals — Q6790088 on Linux, Q36155219 on macOS and Q30401460 on Windows, over a million views between them — all have accepted answers that put psql's bin directory on PATH. Together with the install step, the diagnosis 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). The psql \COPY command supports CSV export with headers to include column names. If psql connects but Prisma still cannot reach the database, see fixing Prisma's invalid port error.

# 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. Each Debian or Ubuntu release ships one default major, so any other major comes from the PostgreSQL Apt repository (apt.postgresql.org), which carries every supported version. A psql older than the server warns on connect and some backslash commands may fail, so match the server major when you can (see the mistakes list below).

macOS — Homebrew (Intel and Apple Silicon)#

The trap on macOS is thinking libpq is library-only and looking for a separate "postgresql-client" formula — Homebrew has no formula named postgresql-client (brew install postgresql-client fails with "no available formula"). The formula that actually ships psql is libpq itself: it installs 34 client binaries, psql, pg_dump, and pg_restore included. The reason psql still isn't found right after installing it is that libpq is keg-only — Homebrew deliberately does not symlink it into your PATH, because a full PostgreSQL server install also provides these binaries and Homebrew avoids the conflict.

brew install libpq
which psql
# nothing — libpq is keg-only, not linked yet

Link it or add it to PATH — either works. brew link symlinks the keg's files into Homebrew's prefix (--force is what allows a keg-only formula to be linked), so after Option A psql resolves from $(brew --prefix)/bin:

# Option A: force-link libpq's binaries into your Homebrew prefix
brew link --force libpq
which psql
# /opt/homebrew/bin/psql  (Apple Silicon) — a symlink into the libpq keg
# /usr/local/bin/psql     (Intel)
 
# Option B: add libpq's bin directory to PATH instead (safer if you might
# also install a full PostgreSQL server formula later — avoids symlink clashes)
echo 'export PATH="'$(brew --prefix libpq)'/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you specifically want a full PostgreSQL install (server + client) instead of just the client library, install a versioned formula — Homebrew ships PostgreSQL per major version, there is no unversioned postgresql formula either (brew install postgresql still works because postgresql and postgres are aliases of postgresql@18):

brew install postgresql@18   # also keg-only — link it or add to PATH the same way
brew link postgresql@18

For Apple Silicon Macs, Homebrew lives at /opt/homebrew — make sure your zsh startup file (zsh is the default on macOS 10.15+) contains the Homebrew path. Homebrew's installer does not write this line for you: its "Next steps" output tells you to append it to ~/.zprofile (install.sh), so if you skipped that step, add it now:

# ~/.zprofile — the installer prints this line under "Next steps"; it does not add it
eval "$(/opt/homebrew/bin/brew shellenv)"

After editing ~/.zprofile, source ~/.zprofile 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 (the postgresql package is a metapackage that currently installs postgresql18):

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

Option B — EDB installer (official)#

Download from postgresql.org/download/windows and run the installer. At the Select Components step, Command Line Tools must stay checked — that is the component that installs psql, pg_dump and the other client programs; the PostgreSQL Server component is optional if you only want psql. By default the installer does not modify the system PATH, so add C:\Program Files\PostgreSQL\<major>\bin to Path yourself (System Properties → Environment Variables), then open a new terminal. The installer also drops a SQL Shell (psql) shortcut in the Start Menu. That shortcut runs a script that calls psql.exe by its full path, with prompts for server, database, port, user, and password — so it works before you touch PATH.

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, the database container is named supabase_db_ followed by your project_id from supabase/config.toml, which defaults to the folder name (CLI source):

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_id> 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 only the library. On Debian/Ubuntu, libpq-dev ships libraries and headers, while psql comes from postgresql-client-NN. The server metapackage is not the problem: postgresql-17 depends on postgresql-client-17, so apt install postgresql already brings psql.
• Looked for a postgresql-client Homebrew formula. It does not exist. libpq is the formula that ships psql on macOS — it's just keg-only, so it needs brew link --force libpq or a PATH entry before psql resolves.
• Wrong PATH on Apple Silicon. psql is at /opt/homebrew/opt/libpq/bin/psql, not /usr/local. Add /opt/homebrew/opt/libpq/bin to PATH, or run brew link --force libpq.
• 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 older than the server. On connect psql prints WARNING: psql major version 15, server major version 16. followed by Some psql features might not work. (psql source); a newer psql against an older server only shows both versions in its banner. Plain SQL generally still runs, but backslash commands are particularly likely to fail against a newer server — install a client of the server's major version (or newer) to clear it.

Official references: PostgreSQL — Client Applications (psql), PostgreSQL — Downloads, Homebrew — libpq formula, 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'.

The setting it names, pgsql.pgBinaryDirs, belongs to Microsoft's PostgreSQL extension for VS Code (ms-ossdata.vscode-pgsql), whose dump and restore UI needs the PostgreSQL client binaries such as pg_dump. The message covers two cases: the client binaries are not installed at all, or they are installed in a directory the extension's process does not search.

On macOS, the Homebrew libpq formula installs binaries into an architecture-specific, keg-only path (/opt/homebrew/opt/libpq/bin on Apple Silicon, /usr/local/opt/libpq/bin on Intel). Even after brew link --force libpq makes them resolve in your terminal, that only works because your shell's startup file puts the Homebrew prefix on PATH (on macOS zsh, Homebrew's installer tells you to add its shellenv line to ~/.zprofile). Apps started from Finder, Spotlight, or the Dock are not started from that shell. VS Code compensates by running your shell once at launch to resolve its environment, but if that takes longer than application.shellEnvironmentResolutionTimeout (10 seconds by default) or fails, it starts without your shell's PATH.

The fix: configure pgsql.pgBinaryDirs#

VS Code’s PostgreSQL extension accepts an explicit list of binary directories. Open VS Code Settings (JSON), and add the path that matches your architecture. The key is spelled pgsql.pgBinaryDirs (an array of strings) in the extension's manifest, even though search results show the error message in lower case:

{
  "pgsql.pgBinaryDirs": ["/opt/homebrew/opt/libpq/bin"]
}

For Intel Macs, use "/usr/local/opt/libpq/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 client package is installed (postgresql-client on Debian/Ubuntu, postgresql on Fedora/RHEL).

Why this happens even when psql works in your terminal#

Your terminal runs a shell that reads your startup files, and that is where the Homebrew prefix gets onto PATH — Homebrew's installer does not write it there itself; it prints the line for you to add. VS Code launched from the Dock only sees that PATH if its shell-environment resolution succeeds at startup; when it times out or fails, VS Code runs without your shell's environment and the Homebrew prefix is absent. The pgsql.pgBinaryDirs setting names the directory explicitly, which is exactly what the error message asks for.

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.

Further reading: Fix PostgreSQL Server Won't Start on Mac OS X (2026).