PostgreSQL in Docker: Run Postgres with Docker & Docker Compose

Run PostgreSQL in Docker with docker run

Running PostgreSQL in Docker needs only Docker itself. On Windows 11 that is Docker Desktop, whose default backend is WSL 2; on macOS it is Docker Desktop; on Linux, Docker Engine. The postgres image is a Docker Official Image, so it is pulled by its short name. On 8 October 2026 the 18 and latest tags point to PostgreSQL 18.6, and PostgreSQL 14 to 17 have their own major-version tags. PostgreSQL 19 is in beta (tag 19beta4); the PostgreSQL project does not advise running beta versions in production.

Pin a major version tag such as postgres:18 rather than latest, so a future major release does not start against data files it cannot read. The command below starts a server, publishes port 5432 to the host and keeps the data in a named volume:

docker run --name pg -e POSTGRES_PASSWORD=<your-password> -p 5432:5432 -v pgdata:/var/lib/postgresql -d postgres:18

docker exec -it pg psql -U postgres

Docker mount for Postgres data: volumes and the PostgreSQL 18 change

A container's writable layer is deleted with the container, so the database files must live in a volume or a bind mount. Docker describes volumes as the preferred mechanism for persisting container data, and a named volume such as pgdata survives docker rm. Note that docker compose down -v removes named volumes declared in the Compose file, which deletes the database.

The image changed its layout in PostgreSQL 18. PGDATA is now version specific (/var/lib/postgresql/18/docker) and the declared VOLUME is /var/lib/postgresql. Mount your volume at /var/lib/postgresql for 18 and later; this lets a future major upgrade use pg_upgrade --link across the two version folders. For PostgreSQL 17 and earlier the image documentation is explicit: mount at /var/lib/postgresql/data, because a mount at /var/lib/postgresql does not persist data on those versions. Data is then written to an anonymous volume that is not reused when the container is re-created.

A bind mount (-v /my/own/datadir:/var/lib/postgresql) puts the files in a known folder on the host, at the cost of managing directory permissions yourself. The image runs as the postgres system user, and running it as another UID needs the extra steps in the image's "Arbitrary --user Notes".

Docker Compose file for PostgreSQL and pgAdmin

For a local development stack, a compose.yaml is easier to keep than a long docker run line. The file below follows the current Compose Specification: there is no top-level version: key, which Docker documents as obsolete. It combines the image's own example (including shm_size), Docker's documented pg_isready healthcheck for postgres:18, and the pgAdmin container's required variables.

services:
  db:
    image: postgres:18
    restart: unless-stopped
    shm_size: 128mb
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql
      - ./initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s

  pgadmin:
    image: dpage/pgadmin4:latest
    restart: unless-stopped
    environment:
      PGADMIN_DEFAULT_EMAIL: you@example.com
      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD:?set PGADMIN_PASSWORD in .env}
    ports:
      - "5050:80"
    volumes:
      - pgadmin:/var/lib/pgadmin
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:
  pgadmin:

POSTGRES_PASSWORD=<your-password>
PGADMIN_PASSWORD=<your-pgadmin-password>

Start the stack and register the server in pgAdmin

1. Save both files in one folder and run docker compose up -d. Compose reads the .env file in the project directory; the ${VAR:?error} form stops with an error if a password is missing.
2. Run docker compose ps and wait until db reports healthy. Compose only starts pgadmin after the healthcheck passes.
3. Open http://localhost:5050 and sign in with PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD. Without PGADMIN_ENABLE_TLS, the container listens on port 80 in plain text, which is why the file maps host port 5050 to 80.
4. Register a server with host name db (the Compose service name), port 5432, user app and your password. Inside a Compose network each service is reachable by its service name; localhost would point at the pgAdmin container itself.

The pgAdmin documentation says the container runs as UID 5050, mounts /var/lib/pgadmin for its settings, and includes pg_dump, pg_dumpall, pg_restore and psql for several PostgreSQL versions, so backups and restores can be run from pgAdmin as well as from the command line. To pre-load server definitions, mount a servers.json file at /pgadmin4/servers.json.

Initialisation scripts in /docker-entrypoint-initdb.d

To create tables or load sample data on first start, put *.sql, *.sql.gz or *.sh files in a folder mounted at /docker-entrypoint-initdb.d (the ./initdb folder in the Compose file above). After initdb creates the default user and database, the entrypoint runs .sql files, runs executable .sh files and sources non-executable ones, in sorted name order. SQL files are executed as POSTGRES_USER.

Two documented catches: the scripts run only when the container starts with an empty data directory, and if a script fails, the entrypoint exits and a restart with the now-initialised directory will not run the remaining scripts. To re-run them, remove the volume (losing its data) and start again. During initialisation the temporary server listens only on the Unix socket, so psql calls in .sh scripts should not pass a host name.

CREATE TABLE customers (
    customer_id  integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name         text NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now()
);

INSERT INTO customers (name) VALUES ('Ada'), ('Grace');

Connecting from the host: docker postgres localhost and server settings

With -p 5432:5432, tools on the host connect to localhost port 5432 with the user and password you set, for example from pgAdmin desktop or DBeaver. Host connections use scram-sha-256 password authentication by default. Inside the container, Unix-socket connections use trust authentication, which is why docker exec ... psql does not ask for a password.

To publish the port only on your own machine, prefix the host address: -p 127.0.0.1:5432:5432. If a locally installed PostgreSQL already uses 5432, map a different host port (-p 5433:5432) and connect to 5433.

Server settings can be passed after the image name, because the entrypoint forwards them to the postgres server, for example postgres:18 -c shared_buffers=256MB -c max_connections=200. For a full configuration file, mount it and add -c config_file=/etc/postgresql/postgresql.conf; the image documentation notes that such a file must set listen_addresses = '*' so other containers can connect.

Backing up a Postgres container with pg_dump

A named volume is not a backup. The portable way to back up one database is a logical dump made with pg_dump, which is already inside the image. Writing the archive inside the container and copying it out with docker cp avoids shell redirection problems with binary output on Windows:

docker exec pg pg_dump -U postgres -Fc -f /tmp/mydb.dump mydb
docker cp pg:/tmp/mydb.dump ./mydb.dump

docker cp ./mydb.dump pg:/tmp/mydb.dump
docker exec pg createdb -U postgres -T template0 mydb_restored
docker exec pg pg_restore -U postgres -d mydb_restored /tmp/mydb.dump

Version rule for dumps

pg_dump refuses to dump a server with a newer major version than its own, and its output is only guaranteed to load into the same or a newer major version. Running the tool inside the server's own container keeps the versions matched. Formats, parallel restores and pg_dumpall are covered in the pg_dump and pg_restore guide listed under related pages.

Common PostgreSQL Docker errors and fixes

Most problems with the postgres image come from its first-start behaviour. These are the cases the image documentation describes, with the documented fix.

Frequently asked questions

Sources

• postgres Docker Official Image documentation (docker-library/docs)
• PostgreSQL versioning policy
• PostgreSQL home page (current releases)
• pgAdmin 4 documentation: Container Deployment
• Docker docs: Control startup order in Compose
• Docker docs: Volumes
• Docker docs: Compose version and name elements
• Docker docs: Networking in Compose
• Docker docs: docker compose down
• Docker docs: docker container cp
• Docker docs: Install Docker Desktop on Windows
• PostgreSQL 18 documentation: pg_isready
• PostgreSQL 18 documentation: pg_dump

Checked 8 October 2026.

How we research guides: our editorial method. We link only to official downloads and never host installers.