Install PostgreSQL on Linux, macOS and Windows

Which option to pick

For a local development database, install the PostgreSQL server and client together from your package manager. On Linux the distribution package is fine for development; the PostgreSQL project’s own apt and yum repositories (PGDG) give you the newest major version and several side by side. On macOS Homebrew is the easiest, and Postgres.app is a good graphical alternative. On Windows the EDB installer from postgresql.org is the standard. If you already use Docker, docker run postgres:17 is another perfectly good way to get a local server without installing anything; see the Compose entry. Replace 17 below with the current major version.

Step: Linux

Debian and Ubuntu, distribution package:

sudo apt update
sudo apt install postgresql
sudo systemctl status postgresql

To use the PostgreSQL project’s repository for a specific version instead, the postgresql-common package ships a helper that configures it:

sudo apt install postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install postgresql-17

Fedora and RHEL need an explicit initialisation step and the service enabled:

sudo dnf install postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

Step: macOS

brew install postgresql@17
brew services start postgresql@17

Homebrew creates a database cluster owned by your macOS user, so psql postgres connects straight away without a password. If psql is not found, Homebrew prints the PATH line to add for versioned formulas, typically export PATH="$(brew --prefix)/opt/postgresql@17/bin:$PATH". Alternatively install Postgres.app, start it, and follow its instructions to add the command-line tools to PATH.

Step: Windows

winget install PostgreSQL.PostgreSQL.17

Or download the interactive installer from postgresql.org/download/windows. It asks for a password for the postgres superuser; write it down. It installs the server as a Windows service, pgAdmin, and SQL Shell (psql) in the Start menu. To use psql from PowerShell, add C:\Program Files\PostgreSQL\17\bin to your PATH in the environment variable settings.

Check it works

psql --version
pg_isready

pg_isready prints accepting connections when the server is up. Connect as the superuser and create a user and database for your project. On Linux the postgres OS user is allowed in without a password (peer authentication):

sudo -u postgres psql

On macOS with Homebrew use psql postgres; on Windows use psql -U postgres and the password from the installer. Then, inside psql:

CREATE USER app WITH PASSWORD 'choose-a-password';
CREATE DATABASE app OWNER app;
\q

psql -h localhost -U app -d app

Common problems

• psql: error: connection to server on socket ... failed: FATAL: role "yourname" does not exist: plain psql tries to log in with your OS user name. Use sudo -u postgres psql or psql -U app -d app.
• Peer authentication failed for user "app" on Linux: you connected through the Unix socket, where Linux user names must match. Add -h localhost to use a password instead.
• connection refused on port 5432: the service is not running. sudo systemctl start postgresql on Linux, brew services start postgresql@17 on macOS, or start the service in services.msc on Windows.
• Windows: psql is not recognised: the bin folder is not on PATH; use SQL Shell from the Start menu or add the folder as described above.
• Port 5432 already in use: another PostgreSQL (or a Docker container) is running. Stop it or configure a different port in postgresql.conf.

Official documentation

• PostgreSQL downloads
• PostgreSQL tutorial: Getting Started
• psql reference