Installing PostgreSQL on macOS Linux and Windows Today

The first obstacle for a new PostgreSQL user is not SQL. It is getting a server running and finding out which account to use to talk to it. The install differs by platform in small ways that matter: whether a cluster exists after the package installs, which operating system user owns the data, whether the default account has a password. This article walks through each major platform in turn, with the checks that tell you the install worked and the pointers to the usual first-day errors. It is part of setting up PostgreSQL for development without fighting it, and the container route is in running PostgreSQL in Docker with a persistent volume.

Decide the major version first

Package managers install a default, which may not be the version you want. Before installing, decide the major (see which PostgreSQL version to start a new project on): match production if one exists, otherwise a current supported release. Ask for the version explicitly where the platform allows it. The commands below show 17; replace with your choice.

macOS

Two good routes: Homebrew and Postgres.app.

Homebrew.

brew install postgresql@17
brew services start postgresql@17

Homebrew installs the server and client tools under its prefix (/opt/homebrew on Apple silicon, /usr/local on Intel) and does not link versioned formulas into your PATH by default. Add the bin directory to your PATH as the install output suggests, for example export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH". The service runs as your macOS user. The install creates a database cluster with a superuser role named after your macOS account and no password, and a database with the same name, so psql postgres works immediately over the local socket.

Postgres.app. A self-contained application that bundles the server and tools; you start and stop it from the menu bar, and several versions can sit side by side. It is the quickest route for people who want no command line setup, and it has its own data directory under Application Support.

Both leave you with a server on localhost:5432.

Debian and Ubuntu

sudo apt update
sudo apt install postgresql

This installs the distribution's default major and creates and starts a cluster called main. To choose another major, add the PostgreSQL project's apt repository (the instructions are on the download page) and install postgresql-17. The packages create an operating system user postgres, a database superuser postgres without a password, and configuration under /etc/postgresql/<version>/main/ with data in /var/lib/postgresql/<version>/main/.

Local socket connections use peer authentication: you may connect as database user postgres only from the operating system user postgres.

sudo -u postgres psql

The Debian tooling manages clusters: pg_lsclusters lists them, pg_ctlcluster 17 main start controls one, and sudo systemctl status postgresql shows the service. Several majors can coexist, each on its own port.

Red Hat family (RHEL, Rocky, AlmaLinux, Fedora)

The distribution packages and the project's yum repository differ in names. With the project repository enabled:

sudo dnf install postgresql17-server
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable --now postgresql-17

Unlike Debian, installing the package does not create a cluster. The initdb step creates the data directory (/var/lib/pgsql/17/data), and only then can the service start. The configuration files live in the data directory. The postgres operating system user exists; connect with sudo -u postgres psql. The firewall (firewalld) blocks port 5432 from outside by default, which is what you want for a local database.

On Fedora and distribution packages without the project repository, the package is postgresql-server and the setup command is postgresql-setup --initdb.

Windows

Download the installer from the project's download page (it is built by EDB). The wizard asks for:

• Components: the server, pgAdmin, command line tools and optional Stack Builder. The command line tools give you psql.

• Data directory: the default under C:\Program Files\PostgreSQL\17\data is fine.

• Superuser password: for the postgres role. Write it down; this is the password psql asks for, and it is the one people forget.

• Port: 5432 unless something else uses it.

• Locale: the default is the operating system's; for development, a UTF-8 aware setting is fine.

The server installs as a Windows service that starts at boot. Add the bin directory to your PATH to use psql from a terminal, or use the SQL Shell (psql) shortcut, which prompts for server, database, port, user and password with defaults in brackets. Windows Subsystem for Linux is an alternative: install the Linux packages inside it and treat the environment as Debian or Ubuntu, remembering that WSL is a separate machine with its own network address in some configurations.

Check that it works

On any platform, three checks in order.

pg_isready -h localhost -p 5432
psql -h localhost -U postgres -c "SELECT version();"
psql -U postgres -c "SHOW data_directory;"

pg_isready prints localhost:5432 - accepting connections when the server is up. The SELECT version(); shows the full version string, so you know which major you have. SHOW data_directory; tells you where the data is. On Debian and Red Hat family systems, run psql with sudo -u postgres for the socket connection, or supply a password when connecting over TCP with -h localhost once you have set one.

If pg_isready says no response, the service is not running or listens elsewhere (fixing connection refused on port 5432 in PostgreSQL). If psql says peer authentication failed, you connected over the socket as the wrong operating system user (fixing peer authentication failed for user postgres).

Set a password for the superuser

On Debian, Red Hat family and macOS installs, the postgres role may have no password. Set one if you will connect over TCP, and use \password so the text does not appear in history or the server log.

sudo -u postgres psql

\password postgres

Then create a role and database for your project instead of working as postgres (creating your first database user and schema in PostgreSQL).

Keep the tools on your PATH

The server packages include client programs: psql, pg_dump, pg_restore, createdb, dropdb, pg_isready. If you have more than one major installed, the first on your PATH wins, which can mean running a version 16 pg_dump against a 17 server. A newer pg_dump can dump an older server; an older pg_dump cannot dump a newer one and will refuse. Check with psql --version and which psql, and put the client for your newest server first.

Upgrading and removing

Minor updates (17.4 to 17.5) install through the package manager and restart the service; they never change the data format. Major upgrades are a project: dump and restore, or pg_upgrade. Removing a package does not always remove its data. On Debian, apt remove keeps the cluster's data and apt purge removes configuration; check before assuming a clean slate. On Windows, the uninstaller asks whether to remove the data directory. Make a dump before removing anything you might want.

Common first-day problems

Port in use. Another PostgreSQL (an old install, Postgres.app, Docker) already listens on 5432. Use lsof -i :5432 or ss -ltnp | grep 5432 to find it, stop it or choose another port.

Service starts then stops. Look at the log. A data directory with wrong permissions (it must be owned by the server user and not readable by others, mode 0700), a leftover postmaster.pid after a crash or a full disk are the usual causes.

Wrong version running. You installed 17 and a 15 server still answers on 5432. SELECT version(); shows which one you reached.

Command not found. The binaries are installed but not on your PATH, typical for Homebrew versioned formulas and for Red Hat family paths under /usr/pgsql-17/bin.

When a package install is the wrong route

A package install is the wrong route when you need several versions at once and want them isolated: containers do that without PATH juggling. It is the wrong route for continuous integration and disposable test environments, where an image started in seconds beats a service installed on the runner. And it is the wrong route when your organization provides a managed development database, which should be used so that everyone shares a configuration. For everything else, a native install is quick and familiar. The authoritative instructions are on the project's download page, and the server administration chapter of the manual covers installation from source and the service tools.