How to install PostgreSQL on Ubuntu 24.04
We earn commissions when you shop through the links below.
We installed PostgreSQL on a fresh Ubuntu 24.04 and kept what every command printed, from the first login and “Peer authentication failed” to removing it all again.
Short answer: sudo apt update, then
sudo apt install -y postgresql. On 5 October 2026 that gave us PostgreSQL 16.15,
running and listening on this machine only. The first login is
sudo -u postgres psql.
psql -U postgres fails with Peer authentication failed for user "postgres",
and that is the install working as it was set up. Over the local socket PostgreSQL lets you in
only as the database user that has your system user's name. Further down are the reason, two
fixes that we ran, a user and a database of your own, and how to remove everything, down to
what the packages leave behind.
What this was run on, and what it does not cover
We ran every command on this page on a fresh virtual machine at a cloud provider, started from Ubuntu's official 24.04 server image, with nothing installed or changed on it beforehand. A script ran the commands and kept everything the machine printed. A block marked Output shows what the command above it printed, or the lines of it that matter. A line is always shown whole, except that lines from the server's own log are shown without the time and the process number they start with. This is what the machine said about itself.
date -u +%Y-%m-%d
lsb_release -a
nproc
free -m
2026-10-05
Distributor ID: Ubuntu
Description: Ubuntu 24.04.5 LTS
Release: 24.04
Codename: noble
2
total used free shared buff/cache available
Mem: 3908 457 3265 0 403 3450
That is one machine on one day. The PostgreSQL you get is the one Ubuntu's archive has on the
day you install, so the version numbers below may not be yours. A few other things will differ
too. The image's user is called ubuntu and may use sudo without a
password, so where a message below says ubuntu, yours says your own user's name.
The address of Ubuntu's archive in apt's first lines depends on where your machine is, and we
left those lines out.
A script has no terminal, and some commands need one: psql's prompt, a password, a yes-or-no question before something is removed. In those places the script ran the command under a pseudo-terminal and typed the answers, and the Output block shows them as the terminal echoed them. The script also ran every command in a shell of its own, while your terminal is one shell for all of them.
This page doesn't cover reaching the database from another machine (the listen address, the firewall, TLS), backups, or tuning. When you are through it, PostgreSQL answers on this machine only.
1. Install PostgreSQL
Ubuntu's package postgresql isn't a PostgreSQL of its own. It's a pointer to the
PostgreSQL that this Ubuntu release ships, here 16. Once apt has fresh package lists, you can
see which version that is before you install anything.
sudo apt update
apt-cache policy postgresql
postgresql:
Installed: (none)
Candidate: 16+257build1.1
The candidate is the version that the next command installs.
sudo apt install -y postgresql
apt prints a great deal while it works. Two parts are worth a look, the list of packages it adds and the line with which it creates the database cluster.
The following NEW packages will be installed:
libcommon-sense-perl libjson-perl libjson-xs-perl libllvm17t64 libpq5
libtypes-serialiser-perl postgresql postgresql-16 postgresql-client-16
postgresql-client-common postgresql-common ssl-cert
Creating new PostgreSQL cluster 16/main ...
/usr/lib/postgresql/16/bin/initdb -D /var/lib/postgresql/16/main --auth-local peer --auth-host scram-sha-256 --no-instructions
The options --auth-local peer --auth-host scram-sha-256 in that last line are where
the error of section 4 comes from. The package list comes back in section 9, because these
packages are what an undo has to take away again.
2. Check what you got
The candidate above was a package's version number. psql reports its own version, and that's the PostgreSQL release it came with.
psql --version
psql (PostgreSQL) 16.15 (Ubuntu 16.15-0ubuntu0.24.04.1)
There's nothing to switch on afterwards. The install enabled the service, and the cluster is online.
systemctl is-enabled postgresql
pg_lsclusters
enabled
Ver Cluster Port Status Owner Data directory Log file
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log
One thing here looks like a fault the first time you see it. Ask systemd about the unit
postgresql.service, and its answer begins like this.
systemctl status postgresql --no-pager --lines=0
● postgresql.service - PostgreSQL RDBMS
Loaded: loaded (/usr/lib/systemd/system/postgresql.service; enabled; preset: enabled)
The next line starts with Active: active (exited). Nothing is wrong, and the
server hasn't stopped. This unit has no running process, and the server runs in a second unit,
postgresql@16-main.service.
systemctl status postgresql@16-main --no-pager --lines=0
● postgresql@16-main.service - PostgreSQL Cluster 16-main
Loaded: loaded (/usr/lib/systemd/system/postgresql@.service; enabled-runtime; preset: enabled)
Its next line starts with Active: active (running). The server listens on port 5432
of this machine only (127.0.0.1) and not on the network.
sudo ss -ltnp | grep 5432
LISTEN 0 200 127.0.0.1:5432 0.0.0.0:* users:(("postgres",pid=4085,fd=6))
3. The first login
The install made one database user, postgres, a superuser without a password, and
a system user of the same name, which was not there before. You log in by becoming that system
user for one command. At psql's prompt the script typed \conninfo, which says how
you are connected, and \q, which leaves.
sudo -u postgres psql
psql (16.15 (Ubuntu 16.15-0ubuntu0.24.04.1))
Type "help" for help.
postgres=# \conninfo
You are connected to database "postgres" as user "postgres" via socket in "/var/run/postgresql" at port "5432".
postgres=# \q
With -c, psql runs one command and ends. The rest of this page uses that form,
because it keeps each step to one line. The first of the next two commands lists the database
users, and the second shows whether each of them has a password.
sudo -u postgres psql -c "\du"
List of roles
Role name | Attributes
-----------+------------------------------------------------------------
postgres | Superuser, Create role, Create DB, Replication, Bypass RLS
sudo -u postgres psql -c "SELECT rolname, rolpassword IS NULL AS no_password FROM pg_authid WHERE rolcanlogin;"
rolname | no_password
----------+-------------
postgres | t
(1 row)
The t means true. The superuser has no password, and that matters again in
section 7.
4. The error: Peer authentication failed for user "postgres"
The obvious way to log in as the superuser is to name it with -U. On a fresh
install that is refused.
psql -U postgres
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "postgres"
The message doesn't say what failed to match, but the server's own log does, a few lines from its end.
sudo tail -n 4 /var/log/postgresql/postgresql-16-main.log
postgres@postgres LOG: provided user name (postgres) and authenticated user name (ubuntu) do not match
The provided name is the database user you asked for with -U. The
authenticated name is the system user your command runs as, and the server gets that
from the operating system rather than from anything you type. Peer authentication compares the
two and lets you in when they're the same. On this install that's all peer does, and it's why
sudo -u postgres psql worked in section 3 and this didn't. You only get it on
connections over this machine's socket (the manual's section on
peer authentication).
Which method a connection is checked by is set in the file pg_hba.conf. Here is
ours as the install left it, without its comments and empty lines.
sudo grep -v -e "^#" -e "^$" /etc/postgresql/16/main/pg_hba.conf
local all postgres peer
local all all peer
host all all 127.0.0.1/32 scram-sha-256
host all all ::1/128 scram-sha-256
local replication all peer
host replication all 127.0.0.1/32 scram-sha-256
host replication all ::1/128 scram-sha-256
The lines with replication are for connections that copy the database to another
server, and they don't apply to a login. The server goes through the others from the top, uses
the first one that matches the kind of connection, the database and the user, and tries nothing
after it
(the manual on pg_hba.conf).
A local connection is one over the socket, and for those the file says peer. A
host connection comes over TCP, which this file accepts from this machine only,
and for those it wants a password, with the method scram-sha-256.
That leaves two ways in. You can be the system user, as in section 3. Or the database user can have a password, and then you either come over TCP (section 5) or change one line of this file for that one user (section 6).
Many answers to this error tell you to change peer to trust. We
don't. The manual says that trust lets anyone who can reach the server log in as any
database user, the superuser included, without a password.
5. A user and a database of your own
An application shouldn't log in as the superuser. Give it a user with a password and a database that this user owns. Choose a password of your own, because ours is an example on a public page.
sudo -u postgres psql -c "CREATE ROLE app LOGIN PASSWORD 'example-password-change-me';"
sudo -u postgres createdb --owner=app appdb
CREATE ROLE
On the socket the new user runs into the same rule as before, because no system user is called
app.
psql -U app -d appdb
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "app"
Fix one: come over TCP
The first fix changes no file. With -h localhost the connection comes over TCP,
which makes it a host connection, and those ask for the password. The script
typed the password at the prompt, where a terminal doesn't show it.
psql -h localhost -U app -d appdb -c "\conninfo"
Password for user app:
You are connected to database "appdb" as user "app" on host "localhost" (address "127.0.0.1") at port "5432".
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
For the rest of the page the script hands psql the password in the variable
PGPASSWORD, which keeps a step to one line without a prompt. With it, the new user
can work in its database.
PGPASSWORD=example-password-change-me psql -h localhost -U app -d appdb -c "CREATE TABLE notes (id integer PRIMARY KEY, body text); INSERT INTO notes VALUES (1, 'hello'); SELECT * FROM notes;"
CREATE TABLE
INSERT 0 1
id | body
----+-------
1 | hello
(1 row)
From the manual, not from our run: writing a password into a command line, in
either of the two ways above, is something our script does and not a habit to copy. The manual
does not recommend PGPASSWORD, because some operating systems let other users see
a process's environment variables, and it points to a password file instead
(34.15 Environment Variables).
psql's \password, which section 7 runs, sets a password so that it "does not
appear in cleartext in the command history, the server log, or elsewhere"
(psql in the PostgreSQL 16 manual).
Of a password written after CREATE ROLE … PASSWORD, as above, the manual says that
it "might also be logged in the client's command history or the server log"
(CREATE ROLE, Notes).
6. Fix two: a password on the socket, for this one user
If a program has to use the socket as app, that user needs a line of its own in
pg_hba.conf. The line has to go above the line for everyone, because the
first match wins. Keep a copy of the file before you touch it. In an editor you would add the
one line that the diff below shows, and the script did the same with
sed.
sudo cp /etc/postgresql/16/main/pg_hba.conf /etc/postgresql/16/main/pg_hba.conf.before
sudo sed -i "/^local[[:space:]]\+all[[:space:]]\+all[[:space:]]\+peer/i local all app scram-sha-256" /etc/postgresql/16/main/pg_hba.conf
sudo diff /etc/postgresql/16/main/pg_hba.conf.before /etc/postgresql/16/main/pg_hba.conf || true
122a123
> local all app scram-sha-256
The numbers are line numbers of our file (122a123 here, and 118, 123 and 124 below), and yours
may differ. What counts is that the new line is above local all all peer.
The view pg_hba_file_rules lets you check the edit before it is in force. It shows the file as it is now, not what the server has loaded, and its
last column has an error for a line the server could not use
(the manual on the view).
sudo -u postgres psql -c "SELECT line_number, type, database, user_name, address, auth_method, error FROM pg_hba_file_rules;"
line_number | type | database | user_name | address | auth_method | error
-------------+-------+---------------+------------+-----------+---------------+-------
118 | local | {all} | {postgres} | | peer |
123 | local | {all} | {app} | | scram-sha-256 |
124 | local | {all} | {all} | | peer |
The new line is there, above the line for everyone, and its last column is empty. The server doesn't use it yet, though. It reads the file when it starts and when it is told to reload, so until then the login fails as before.
PGPASSWORD=example-password-change-me psql -U app -d appdb -c "\conninfo"
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "app"
After a reload the same command works.
sudo systemctl reload postgresql
PGPASSWORD=example-password-change-me psql -U app -d appdb -c "\conninfo"
You are connected to database "appdb" as user "app" via socket in "/var/run/postgresql" at port "5432".
The new line is for one user, so nothing else changed. We ran both earlier logins again after
the reload: the system user still gets in without a password, and psql -U postgres
still fails with the peer error.
sudo -u postgres psql -c "\conninfo"
You are connected to database "postgres" as user "postgres" via socket in "/var/run/postgresql" at port "5432".
7. If something else goes wrong
These are other errors you may meet on a new install. We caused each of them ourselves, and each is followed by its fix or by the section that has it.
role "ubuntu" does not exist
psql
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: role "ubuntu" does not exist
Without -U, psql asks for the database user with your system user's name, and there
is none. Either name a user that exists (-U app) or make one with your own name.
sudo -u postgres createuser "$(whoami)"
database "ubuntu" does not exist, database "app" does not exist
With that user made by createuser, the same command gets further and stops at the
next thing that is missing.
psql
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: database "ubuntu" does not exist
PGPASSWORD=example-password-change-me psql -h localhost -U app
psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: database "app" does not exist
Without -d, psql asks for a database with the same name as the user. The login
itself worked both times and only the database was missing, so the fix is to name the one you
mean.
psql -d appdb -c "\conninfo"
You are connected to database "appdb" as user "ubuntu" via socket in "/var/run/postgresql" at port "5432".
You get the same message for a name you mistyped, and
sudo -u postgres psql -l lists the databases there are.
sudo -u postgres psql -d shop
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: database "shop" does not exist
password authentication failed for user "app"
The password is wrong. psql prints this message twice.
PGPASSWORD=wrong psql -h localhost -U app -d appdb
psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "app"
connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "app"
If the password is lost, the superuser can set a new one. The old one stops working with it: after the change, the first password is refused.
sudo -u postgres psql -c "ALTER ROLE app PASSWORD 'another-example-password';"
PGPASSWORD=example-password-change-me psql -h localhost -U app -d appdb -c "\conninfo"
ALTER ROLE
psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "app"
connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "app"
That form writes the new password into the command. At a terminal, \password
asks for it instead, twice, and shows nothing of it. The script typed
a-third-example-password, and the login after it uses that one.
sudo -u postgres psql -c "\password app"
Enter new password for user "app":
Enter it again:
PGPASSWORD=a-third-example-password psql -h localhost -U app -d appdb -c "\conninfo"
You are connected to database "appdb" as user "app" on host "localhost" (address "127.0.0.1") at port "5432".
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
password authentication failed for user "postgres"
Over TCP the superuser is asked for a password like everyone else, and whatever you give is refused.
PGPASSWORD=anything psql -h localhost -U postgres
psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "postgres"
connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "postgres"
The message is the one for a wrong password, but here no password can be right. Only the server's log says why.
sudo tail -n 4 /var/log/postgresql/postgresql-16-main.log
postgres@postgres DETAIL: User "postgres" has no password assigned.
The superuser has no password after the install (section 3), and a user without one always fails a password check (the manual on password authentication). Log in as in section 3, or use a user of your own.
8. If you need a newer PostgreSQL than Ubuntu ships
Ubuntu keeps one PostgreSQL version for the life of a release, and for 24.04 that is 16. The
PostgreSQL project has its own package repository with newer versions. We tried it on a second
fresh machine of the same kind, also on 5 October 2026, with the commands of
the project's download page for Ubuntu.
The project's script reads a key press before it writes anything, but
among its options is y. We ran it with -y, and it didn't wait.
sudo apt update
sudo apt install -y postgresql-common
grep -n -e getopts -e "read " /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh || true
27:while getopts "c:f:h:ipstv:y" opt ; do
128: read enter
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y
This script will enable the PostgreSQL APT repository on apt.postgresql.org on
your system. The distribution codename used will be noble-pgdg.
sudo apt install -y postgresql-18
psql --version
psql (PostgreSQL) 18.6 (Ubuntu 18.6-1.pgdg24.04+2)
The rules for logging in are the same as with Ubuntu's own package, and so is the error.
sudo grep -v -e "^#" -e "^$" /etc/postgresql/18/main/pg_hba.conf
local all postgres peer
local all all peer
host all all 127.0.0.1/32 scram-sha-256
host all all ::1/128 scram-sha-256
local replication all peer
host replication all 127.0.0.1/32 scram-sha-256
host replication all ::1/128 scram-sha-256
psql -U postgres
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "postgres"
On this second machine we went only as far as the install and the first error. Everything else on this page was run with version 16 from Ubuntu's archive, not with 18.
9. How to undo it
One of the two commands in this section can delete your databases, so know which one
before you type either. apt remove takes the programs away and keeps your
configuration, your databases and the log. apt purge asks whether to delete them
too, and deletes them if you answer yes. In one form, shown further down, it doesn't ask at
all.
Remove: the programs go, the data stays
sudo apt remove -y postgresql postgresql-16 postgresql-client-16 postgresql-common postgresql-client-common
sudo ls /etc/postgresql/16/main
sudo ls /var/lib/postgresql/16/main
ls /var/log/postgresql
pg_hba.conf
pg_hba.conf.before
pg_ident.conf
postgresql.conf
PG_VERSION
base
global
postgresql-16-main.log
The configuration, the data folder and the log are still there. The server isn't. Nothing listens on port 5432 any more, so the next command printed nothing and ended with an error.
sudo ss -ltnp | grep 5432
Purge: it asks, and "no" keeps your data
Typed at a terminal without -y, the purge asks two questions. apt asks whether to
continue, and then the package asks whether to delete the databases.
The script typed y to the first and no to the second.
sudo apt purge postgresql postgresql-16 postgresql-client-16 postgresql-common postgresql-client-common
Do you want to continue? [Y/n] y
Removing the PostgreSQL server package will leave existing database clusters
intact, i.e. their configuration, data, and log directories will not be removed.
On purging the package, the directories can optionally be removed.
Remove PostgreSQL directories when package is purged? [yes/no] no
After "no" the three folders held what they held before, which we checked with the same three
ls commands. A new install then found the cluster again, with the
database of section 5 in it.
sudo apt install -y postgresql
sudo -u postgres psql -c "\l appdb"
Name | Owner | Encoding | Locale Provider | Collate | Ctype | ICU Locale | ICU Rules | Access privileges
-------+-------+----------+-----------------+---------+---------+------------+-----------+-------------------
appdb | app | UTF8 | libc | C.UTF-8 | C.UTF-8 | | |
(1 row)
Purge, answered "yes": the databases are deleted
We ran the same command again, and this time the script typed y and then yes.
sudo apt purge postgresql postgresql-16 postgresql-client-16 postgresql-common postgresql-client-common
Remove PostgreSQL directories when package is purged? [yes/no] yes
Dropping cluster main...
ls -ld /etc/postgresql /var/lib/postgresql /var/log/postgresql 2>&1
ls: cannot access '/var/lib/postgresql': No such file or directory
ls: cannot access '/var/log/postgresql': No such file or directory
drwxr-xr-x 3 postgres postgres 4096 Oct 5 12:47 /etc/postgresql
The data and the log are gone, and nothing asks a second time.
The form that deletes without asking
There's a form of the purge that asks nothing at all. With
DEBIAN_FRONTEND=noninteractive the package is told not to ask, and with
-y apt doesn't ask either. We installed once more, so that there was a cluster to
lose, and ran it. It asked nothing and dropped the cluster. Use this form only where you mean
it, in a script for a machine you are throwing away.
sudo DEBIAN_FRONTEND=noninteractive apt purge -y postgresql postgresql-16 postgresql-client-16 postgresql-common postgresql-client-common
Dropping cluster main...
dpkg: warning: while removing postgresql-common, directory '/etc/postgresql' not empty so not removed
What is still there, and how to remove that too
A few things outlive even the purge. In /etc/postgresql stays whatever the
packages didn't make, which here was our copy from section 6. We deleted the folder and then ran
apt autoremove, which removes every package apt considers no longer needed, not
only PostgreSQL's. On our fresh machine those were the packages the install had brought with it.
On a machine with a history, read its list before you add -y.
sudo find /etc/postgresql
/etc/postgresql
/etc/postgresql/16
/etc/postgresql/16/main
/etc/postgresql/16/main/pg_hba.conf.before
sudo rm -r /etc/postgresql
sudo apt autoremove -y
The following packages will be REMOVED:
libcommon-sense-perl libjson-perl libjson-xs-perl libllvm17t64 libpq5
libtypes-serialiser-perl ssl-cert
Even after all that, the machine wasn't as we had found it. The package ssl-cert
was removed but not purged (state rc), the certificate and the key it made at the
install were still there, and so were the system user postgres and the groups
postgres and ssl-cert. We looked for the user, the two groups and
the package before the first apt command and found none, and the
certificate and the key both carry the time of the install, to the minute. On a machine where something else uses
ssl-cert or a user called postgres, leave them. On ours, the commands
of the last block took them away, and afterwards the same checks found nothing.
dpkg -l | grep "^rc"
sudo ls -l /etc/ssl/certs/ssl-cert-snakeoil.pem /etc/ssl/private/ssl-cert-snakeoil.key
getent passwd postgres
getent group postgres ssl-cert
rc ssl-cert 1.1.2ubuntu1 all simple debconf wrapper for OpenSSL
-rw-r--r-- 1 root root 1135 Oct 5 12:47 /etc/ssl/certs/ssl-cert-snakeoil.pem
-rw-r----- 1 root ssl-cert 1704 Oct 5 12:47 /etc/ssl/private/ssl-cert-snakeoil.key
postgres:x:110:114:PostgreSQL administrator,,,:/var/lib/postgresql:/bin/bash
postgres:x:114:
ssl-cert:x:113:postgres
sudo apt purge -y ssl-cert
sudo deluser postgres
sudo delgroup ssl-cert
info: Removing user `postgres' ...
info: Removing group `ssl-cert' ...
How much this database can take
Installing PostgreSQL is the easy part. How much load one PostgreSQL can take is a different question, and we measured that on real machines: how many requests per second one Postgres handles, how big its connection pool should be, and how many users a $12 server with Nginx, Node.js and Postgres carries.
The app is free to try in your browser, without an account. To hear when Pro is ready, join the waitlist.
Sources
- Our own run: a script on two fresh Ubuntu 24.04 machines on 5 October 2026. Every command and every output on this page is from the script and its log, and the one paragraph marked as being from the manual is the manual's.
- The PostgreSQL project, Linux downloads (Ubuntu): Ubuntu ships one PostgreSQL version per release; the project's Apt repository and its commands.
- PostgreSQL 16 manual, 21.1
The pg_hba.conf File: the first matching line is used and no other;
localandhost;trust; the file is read at start and at a reload. And 54.9 pg_hba_file_rules: the view shows the file as it is, with an error for a line that could not be used. - PostgreSQL 16 manual, 21.9 Peer Authentication and 21.5 Password Authentication.
- PostgreSQL 16 manual, psql:
-c,\q,\password, the default user and database names; 34.15 Environment Variables:PGPASSWORD; and CREATE ROLE, Notes: a password written in the command. - Ubuntu Server documentation,
Install and
configure PostgreSQL: on Ubuntu,
peeris the default for local connections andscram-sha-256for host connections.