Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The shell says psql: command not found

Error-bash: psql: command not found

Short answer

The shell cannot find a psql program. Either the PostgreSQL client package is not installed (common on a server that only has a Docker database, or a fresh Ubuntu), or on macOS Homebrew installed PostgreSQL as keg-only, so its bin folder is not on PATH. Install the client, or add the folder to PATH.

  • Applies to Ubuntu 24.04, macOS with Homebrew, PostgreSQL 17
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the shell whether any psql exists on this machine, and which operating system you are on.

    command -v psql || echo "no psql on PATH"
    uname -s
  2. 2Match what you see, then jump to its fix

    1. 1command -v psql prints nothing and dpkg shows no client package.The PostgreSQL client package is not installed (Ubuntu and Debian)Fix
    2. 2brew list shows postgresql@NN but command -v psql prints nothing.Homebrew installed a versioned PostgreSQL as keg-only (macOS)Fix

What does the error look like?

  • -bash: psql: command not found
  • psql works on the database host but not on the application server

Cause 1 of 2

The PostgreSQL client package is not installed (Ubuntu and Debian)

1Check

The PostgreSQL project splits the client binaries (postgresql-client-N) from the server (postgresql-N). A machine that only runs your app needs the client.

dpkg -l | grep postgresql-client

2Fix

Install the client package. Ubuntu's own repository has one version per release; the PostgreSQL apt repository offers a version of your choice.

sudo apt update
sudo apt install postgresql-client
# or, with the PostgreSQL apt repository, a specific version
sudo apt install postgresql-client-18

3Verify

psql reports its version.

psql --version

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 2

Homebrew installed a versioned PostgreSQL as keg-only (macOS)

1Check

Homebrew's FAQ says a keg-only formula is installed in the Cellar and not linked into the default prefix, so most tools will not find it. brew info prints the PATH line to use.

brew list | grep postgresql
brew info postgresql@17

2Fix

Add the formula's bin folder to PATH, in the line brew info shows. For zsh, put it in ~/.zshrc and open a new terminal.

echo 'export PATH="'"$(brew --prefix postgresql@17)"'/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3Verify

psql now resolves.

command -v psql && psql --version

Confirmed by docs.brew.sh

Did this fix it?

How do I stop it coming back?

  • In provisioning scripts, install postgresql-client explicitly instead of assuming it comes with another package.
  • On macOS, copy the PATH line that brew info prints rather than guessing the folder.
  • Check command -v psql in the same user and shell that your scripts and cron jobs use.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.