Install PostgreSQL

You can learn a lot in the browser, but sooner or later you need a real PostgreSQL server on your own computer: to run psql commands, connect a Python or PHP app, make backups and create users. Installing it takes about ten minutes.

This lesson shows the official way to install PostgreSQL 18 on Windows, macOS, Linux and Docker, and how to check that it works. Pick the section for your system; you do not need to read the others.

What gets installed

Whatever your system, a PostgreSQL installation has the same parts:

The server listens on port 5432 by default. A port is a numbered door on your computer that programs use to talk to each other. MySQL uses port 3306, so PostgreSQL and XAMPP's MySQL or MariaDB can run side by side without any conflict.

Windows

1. Open the official download page at https://www.postgresql.org/download/windows/ and follow the link to the installer certified by EDB. Download the newest 18.x version for Windows x86-64.
2. Run the installer. Keep the default components: PostgreSQL Server, pgAdmin 4, Stack Builder and Command Line Tools.
3. Keep the default data directory.
4. Choose a password for the postgres superuser and write it down safely. You will need it every time you connect.
5. Keep port 5432 and the default locale, then finish. You can skip Stack Builder for now.

The server is now installed as a Windows service that starts automatically. To use psql from any terminal, add the bin folder to your Path environment variable: C:\Program Files\PostgreSQL\18\bin. Then open a new PowerShell window and check:

psql --version
psql -U postgres

psql (PostgreSQL) 18.6
Password for user postgres:

Type the password you chose (nothing appears while you type; that is normal) and press Enter. You can also open SQL Shell (psql) from the Start menu, which asks for the server, database, port and user one by one; press Enter to accept each default in square brackets.

macOS

You have three good choices:

• Postgres.app (easiest): download it from https://postgresapp.com, drag it to Applications, open it and click Initialize. Add /Applications/Postgres.app/Contents/Versions/latest/bin to your PATH as its website explains.
• Homebrew: install a fixed major version and start it as a background service.
• EDB installer: the same graphical installer as on Windows, with pgAdmin included.

With Homebrew, the commands are:

brew install postgresql@18
brew services start postgresql@18
echo 'export PATH="$(brew --prefix)/opt/postgresql@18/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
psql postgres

The versioned formula postgresql@18 is "keg-only", which means Homebrew does not put its programs on your PATH automatically; the echo line does that. Homebrew creates a superuser with your macOS user name, so psql postgres connects you to the built-in postgres database without a password.

Linux (Ubuntu and Debian)

Ubuntu includes PostgreSQL in its own package list, but that is one fixed version. The PostgreSQL project runs its own Apt repository (a package source) with every supported version and its updates. Its helper script adds the repository for you:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt update
sudo apt install -y postgresql-18
sudo systemctl status postgresql

The server starts automatically. On Linux, the postgres database user is matched with a postgres operating-system user, and local connections use peer authentication: the server trusts your Linux login name instead of asking for a password. So you connect like this, and then create a role for your own login so you can work without sudo:

sudo -u postgres psql
sudo -u postgres createuser --superuser "$USER"
createdb "$USER"
psql

Fedora, Red Hat and other distributions have their own instructions on the same download page.

Docker

If you already use Docker, this is the quickest way to get a clean server that you can delete later. The official image is called postgres:

docker run --name pg18 -e POSTGRES_PASSWORD=choose-a-password -p 5432:5432 -v pgdata:/var/lib/postgresql -d postgres:18
docker exec -it pg18 psql -U postgres

POSTGRES_PASSWORD is required and sets the postgres password. -p 5432:5432 makes the server reachable from your computer, and the pgdata volume keeps your data when the container is removed. For PostgreSQL 18 and later, the image expects the volume at /var/lib/postgresql; older guides mount /var/lib/postgresql/data, which is correct only for version 17 and below.

Check that everything works

Once psql shows a prompt such as postgres=#, ask the server who and where you are. You can run the same query in the browser right now:

SHOW server_version;
SELECT current_user, current_database();

server_version
--------------
18.6
(1 row)

current_user | current_database
-------------+-----------------
postgres     | postgres
(1 row)

On your own server you will see the minor version you installed. current_user is the role you logged in as, and current_database() is the database you are connected to. Type \q to leave psql.

Common mistakes

• Forgetting the postgres password. On Windows and the EDB installer you set it once. Store it in a password manager; resetting it means editing the server's authentication file.
• psql is not recognised. The bin folder is not on your PATH, or you did not open a new terminal after changing it.
• "Peer authentication failed for user postgres" on Linux. You ran psql -U postgres as your own login. Use sudo -u postgres psql.
• Two servers on one port. If an old PostgreSQL is already running, the new one may pick port 5433. Check the port in the installer summary.

Key points

• Install from the official download page: the EDB installer on Windows, Postgres.app or Homebrew on macOS, the PostgreSQL Apt repository on Ubuntu, or the postgres:18 Docker image.
• The server listens on port 5432 and the first superuser is called postgres.
• psql --version checks the client; SHOW server_version checks the server.
• On Linux, local logins use peer authentication, so start with sudo -u postgres psql.
• Docker needs POSTGRES_PASSWORD, and from version 18 the volume goes at /var/lib/postgresql.

psql -U postgres

SHOW server_version;
SELECT current_user;