The shell says psql: command not found
-bash: psql: command not foundShort 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.
Fix it fast
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 -s2Match what you see, then jump to its fix
What does the error look like?
-bash: psql: command not foundpsql 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-client2Fix
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-183Verify
psql reports its version.
psql --versionConfirmed by postgresql.org
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@172Fix
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 ~/.zshrc3Verify
psql now resolves.
command -v psql && psql --versionConfirmed by docs.brew.sh
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
Databases
psql cannot connect: no such file or directory on the Unix socket
Is the server running locally and accepting connections on that socket?
psql looked for a Unix socket file and found nothing there.
3 causes, each with a fixDatabases
The shell says initdb: command not found after installing PostgreSQL
bash: initdb: command not found
Either the PostgreSQL server package is not installed, or it is installed but initdb is not on your PATH.
3 causes, each with a fixDatabases
DBeaver cannot run pg_restore: the utility is not found in the client home
Utility 'pg_restore' not found in client home '/usr/lib' (/usr/lib)
DBeaver runs pg_restore from a local PostgreSQL client folder; it does not bundle one.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
manage.py test stops with 'permission denied to create database' on PostgreSQL
django.db.utils.ProgrammingError: permission denied to create database
Django creates a separate database called test_ plus your database name, using the DATABASES USER.
2 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fix