PostgreSQL server default port: 5432
PostgreSQL server uses TCP port 5432 by default. When the port is busy, the server does not start. Its log shows a could not bind IPv4 address error ending in Address already in use, and the PostgreSQL manual says this usually means you tried to start another server on the same port where one is already running.
Key facts
| Port | Protocol | Role | Category |
|---|---|---|---|
| 5432 | TCP | PostgreSQL server | Database |
What happens when the port is busy
The server does not start. Its log shows a could not bind IPv4 address error ending in Address already in use, and the PostgreSQL manual says this usually means you tried to start another server on the same port where one is already running. If the kernel error is something other than Address already in use, such as Permission denied, the manual says the problem is probably different. Stop the other server, or give this one its own port.
Change the port
port = 5433The port setting defaults to 5432 and covers every address the server listens on. It is read at server start, so restart the server. The Unix socket file name includes the port, so the socket changes with it.
# in the foreground
postgres -D "$PGDATA" -p 5433
# or in the background with pg_ctl
pg_ctl -D "$PGDATA" -o "-p 5433" start-p sets the port for that run. pg_ctl passes whatever you give -o to postgres, and pg_ctl restart reuses the previous options unless you pass -o again.
# add the -e options your image needs before the image name
docker run -p 5433:5432 postgres:16-alpineThe format is HOST_PORT:CONTAINER_PORT. The server inside the container keeps listening on 5432, so only the left number changes, and your DATABASE_URL must then name 5433.
psql -h localhost -p 5433 mydb
# or with a connection URI
psql "postgresql://localhost:5433/mydb"This tells clients where to connect. It does not move the server. If the server uses a non-default port, every client has to name that port by option, URI, or PGPORT.
Environment variable: PGPORT. Client side. psql and other libpq programs use PGPORT as the port when you do not pass one. To set the server’s port, use port in postgresql.conf or -p. The postgres reference page also says the -p default comes from PGPORT, so an exported PGPORT can change the port of a server you start by hand.
Bind address
listen_addresses defaults to localhost, which allows only local TCP loopback connections, so other machines cannot reach the server out of the box. Set it to * for all interfaces. An empty value turns off TCP/IP and leaves only Unix-domain sockets. One port number covers every address the server listens on. Changing listen_addresses needs a restart.
What else uses this port
No other tool in this dataset uses port 5432 as a default.
The dataset is the 12 tools on the ports index.
Find and free this port
These commands find the process that holds TCP port 5432 and stop it. They come from the Port in use command generator. PID_NUMBER stands for the process ID you read from the first command: replace it before you run the others.
lsof -nP -iTCP:5432 -sTCP:LISTEN
ps -p PID_NUMBER -o pid,ppid,user,command
kill -TERM PID_NUMBERss -ltnp 'sport = :5432'
ps -p PID_NUMBER -o pid,ppid,user,command
kill -TERM PID_NUMBERGet-NetTCPConnection -LocalPort 5432 -State Listen -ErrorAction SilentlyContinue | Select-Object LocalAddress, LocalPort, State, OwningProcess
Get-CimInstance -ClassName Win32_Process -Filter "ProcessId = PID_NUMBER" | Select-Object ProcessId, ParentProcessId, Name, CommandLine
Stop-Process -Id PID_NUMBERRead the output of the second command before you stop anything, because the owner may be a container or another person’s process. Then run the first command again to confirm the port is free.
Next free ports
Counting up from 5432, the next three ports that no tool in this dataset uses as a default are 5433, 5434, and 5435. They are suggestions only: another program on your machine may hold any of them, so run the find command above before you choose one.
In Rig
Rig’s managed PostgreSQL database is a Docker container from the postgres:16-alpine image. Rig opens Adminer on loopback only.
Collisions in practice
The usual collision is a native server and a container that both want 5432. The second one to start usually loses: a second postgres logs a could not bind IPv4 address error, and docker run reports that the port is already allocated. The tempting fix is to stop one and carry on, but your project’s DATABASE_URL still says 5432, so it now reaches whichever server won the port, and that may hold different data from yesterday. Give each project’s database its own host port, write that port into the project’s env file, and change only the left side of -p when you publish a container.
Frequently asked questions
Why does PostgreSQL say could not bind IPv4 address when I start it?
Something already holds the port: another PostgreSQL server, or a container publishing 5432, for example. The PostgreSQL manual says the Address already in use variant of this error usually means you started a second server on the port where one is already running. Find the owner of the port, stop it or choose another port with the port setting or -p, then start again. If the kernel error is different, such as Permission denied, the manual says there is probably a different problem.
Does PGPORT change the port the PostgreSQL server listens on?
PGPORT is a client-side variable. psql and other libpq programs use it as the port when you do not pass one, in the same way as the port connection parameter. Set the server’s port with port in postgresql.conf or with -p. The postgres reference page also describes the -p default as coming from PGPORT, so an exported PGPORT in the shell that launches the server can matter. Set the port explicitly rather than depending on it.
How do I run two PostgreSQL servers on one Mac?
Start each on its own port, set with port in each server’s postgresql.conf or with -p, and give each its own data directory. The Unix socket file is named .s.PGSQL.nnnn after the port, so servers on different ports do not collide there. Every client then has to name the port it wants, with -p, a connection URI such as postgresql://localhost:5433/mydb, or PGPORT.
Sources
- PostgreSQL docs: postgres server reference (-p option, PGPORT)
- PostgreSQL 14 docs: connections and authentication (port setting)
- PostgreSQL docs: connections and authentication (listen_addresses, Unix sockets)
- PostgreSQL docs: pg_ctl (the -o option)
- PostgreSQL docs: starting the database server (start-up failures)
- PostgreSQL docs: libpq environment variables (PGPORT)
- PostgreSQL docs: libpq connection strings and URIs
- Docker docs: publishing and exposing ports
- Docker Desktop docs: troubleshoot topics (port is already allocated)
Busy ports in Rig
When a start fails because a port is taken, Rig shows which process owns it when it can, and lets you reclaim the port or choose another. You do not need Rig to use this page.