How to Install psql on Mac: 3 Quick Methods

This post was written by an engineer at QueryPlane. QueryPlane is an app builder for your database: bring your own postgres db and you can create interactive applications to share with other developers, coworkers or even your customers. If you’re interested in trying it out, get started here.

---

psql is PostgreSQL’s command-line client. It’s the most direct way to connect to a PostgreSQL database — run queries, manage schemas, import and export data, and administer the server. On macOS, there are several ways to install it depending on whether you need just the client or the full PostgreSQL server.

In this post, we’ll cover:

• Homebrew (full PostgreSQL) - Install psql along with the full server
• Homebrew (libpq only) - Install just the client tools without the server
• Postgres.app - Native macOS app with bundled psql
• Verifying the installation - Making sure psql works
• Connecting to a remote database - Using psql without a local server

Option 1: Homebrew with full PostgreSQL

If you need both the PostgreSQL server and client tools, install the full package:

brew install postgresql@17

This installs the PostgreSQL 17 server, psql, and all other client utilities (createdb, pg_dump, pg_restore, etc.). It also initializes a local database cluster.

After installation, add the binaries to your PATH:

echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On Intel Macs, the path is /usr/local/opt/postgresql@17/bin instead.

This is the right option if you’re developing locally and need a PostgreSQL server running on your machine. See our Create a Postgres Database on Mac guide for the full setup walkthrough.

Option 2: Homebrew with libpq (client only)

If you only need psql to connect to a remote database and don’t want to install the full PostgreSQL server, install libpq:

brew install libpq

libpq is PostgreSQL’s C client library. The Homebrew formula includes all the standard client binaries — psql, pg_dump, pg_restore, pg_isready, and others — without installing the server, configuration files, or data directory.

Since libpq is a “keg-only” formula (Homebrew won’t add it to your PATH automatically to avoid conflicts with a full PostgreSQL installation), you need to link it manually:

echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

This gives you a smaller installation footprint. It’s the best option when you’re connecting to a remote PostgreSQL database (like RDS, Cloud SQL, Neon, or Supabase) and don’t need a local server.

Option 3: Postgres.app

Postgres.app is a native macOS application that bundles the PostgreSQL server and all client tools into a standard Mac app. Download it, drag it to your Applications folder, and launch it.

Postgres.app installs the command-line tools in /Applications/Postgres.app/Contents/Versions/latest/bin/. To add them to your PATH, run the setup command from the app’s documentation:

sudo mkdir -p /etc/paths.d && echo /Applications/Postgres.app/Contents/Versions/latest/bin | sudo tee /etc/paths.d/postgresapp

Then open a new terminal window for the PATH change to take effect.

Postgres.app is convenient because it provides a menu bar icon for starting and stopping the server, and it can manage multiple PostgreSQL versions simultaneously. The downside is that it’s a macOS-only solution, so if you switch between macOS and Linux development environments, Homebrew gives you a more consistent workflow.

Verifying the installation

Regardless of which method you used, verify that psql is available:

psql --version

You should see output like:

psql (PostgreSQL) 17.x

If you get “command not found,” the binaries aren’t on your PATH. Double-check the PATH export for your chosen installation method and make sure you’ve opened a new terminal window (or run source ~/.zshrc).

To test a connection to a local server:

psql postgres

This connects to the default postgres database. If the server is running, you’ll see the psql prompt:

postgres=#

Type \q to exit.

Connecting to a remote database

If you installed psql to connect to a remote PostgreSQL instance, use a connection string:

psql "postgresql://username:password@hostname:5432/dbname?sslmode=require"

Or use individual flags:

psql -h hostname -p 5432 -U username -d dbname

Most managed PostgreSQL services (AWS RDS, Google Cloud SQL, Neon, Supabase) provide a connection string in their dashboard that you can paste directly into psql.

To test that your remote connection works without starting a full session:

pg_isready -h hostname -p 5432

This returns a status message without authenticating, useful for checking network connectivity.

Managing multiple PostgreSQL versions

If you work on projects that require different PostgreSQL versions, you might end up with multiple installations. A few things to keep in mind:

Homebrew supports installing multiple versions side by side (brew install postgresql@16 postgresql@17), but only one can be on your PATH at a time. Switch between them by updating the PATH export.

Postgres.app handles multiple versions through its UI. You can run different server versions on different ports and switch between them from the menu bar.

The psql client is generally backward-compatible — a newer psql can connect to older servers. Running psql 17 against a PostgreSQL 14 server works fine for most operations. The reverse (older psql, newer server) can cause issues with newer SQL syntax and features.

Essential psql commands

Once you’re connected, these commands help you navigate:

\l              -- list all databases
\c dbname       -- connect to a different database
\dt             -- list tables in current schema
\d tablename    -- describe a table (columns, types, indexes)
\di             -- list indexes
\df             -- list functions
\du             -- list roles
\x              -- toggle expanded display (useful for wide rows)
\timing         -- toggle query execution timing
\i filename.sql -- execute SQL from a file
\q              -- quit

For query output, \x (expanded mode) is particularly useful when tables have many columns. Instead of a wide table that wraps in your terminal, it displays each row vertically with one column per line.

Wrapping up

For most Mac users, brew install postgresql@17 is the right starting point — you get psql, the server, and all client tools in one command. If you only need the client (no local server), brew install libpq gives you a lighter installation. Postgres.app is a good alternative if you prefer a graphical interface for server management.

Once psql is installed, you can connect to any PostgreSQL database — local or remote. If you prefer a GUI over the command line, see our Top PostgreSQL GUI Clients post.