Docker postgres: 'Database is uninitialized and superuser password is not specified'

Error: Database is uninitialized and superuser password is not specified. — the official postgres Docker image refuses to create a new database without a password for the postgres superuser. It prints this, exits with code 1, and the container stops. Pass POSTGRES_PASSWORD and start it again.

On the command line that is -e POSTGRES_PASSWORD=... on docker run; in Compose it is a POSTGRES_PASSWORD line under environment:. The failed container keeps its name, so remove it with docker rm before reusing it.

The error

$ docker run --name fixes2-ops-nopw postgres:18
Error: Database is uninitialized and superuser password is not specified.
       You must specify POSTGRES_PASSWORD to a non-empty value for the
       superuser. For example, "-e POSTGRES_PASSWORD=password" on "docker run".

       You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all
       connections without a password. This is *not* recommended.

       See PostgreSQL documentation about "trust":
       https://www.postgresql.org/docs/current/auth-trust.html

Why it happens

The image does not start PostgreSQL directly. Its entry point is a shell script, docker-entrypoint.sh, that runs first and prepares the data directory. It looks for a PG_VERSION file in PGDATA (in postgres:18 that is /var/lib/postgresql/18/docker). When the file is missing, the directory is new and the script is about to run initdb, so it calls a check named docker_verify_minimum_env: if POSTGRES_PASSWORD is empty and POSTGRES_HOST_AUTH_METHOD is not trust, it prints the message above and runs exit 1.

That script is the container's main process, so when it exits the container stops. With -d you see only a container ID, and the container is gone from docker ps; docker ps -a shows Exited (1) and docker logs shows the text. The check runs only on an empty data directory. The same image started without a password on a volume that already holds a database printed Skipping initialization and started normally.

The fix

docker run -d --name fixes2-ops-pg -e POSTGRES_PASSWORD=dev-only-password postgres:18
docker exec fixes2-ops-pg psql -U postgres -c "select version();"

The same thing in Compose, started with docker compose -p fixes2-ops up -d:

services:
  db:
    image: postgres:18
    container_name: fixes2-ops-pgc
    environment:
      POSTGRES_PASSWORD: dev-only-password
      POSTGRES_DB: clinic
    ports:
      - "127.0.0.1:5498:5432"
    volumes:
      - pgdata:/var/lib/postgresql

volumes:
  pgdata:

The first logged PostgreSQL init process complete; ready for start up., and both answered psql. Keep real passwords out of the compose file: the entry point also reads POSTGRES_PASSWORD_FILE, which points at a secret file instead. The alternative the message offers, POSTGRES_HOST_AUTH_METHOD=trust, lets anyone who can reach the port log in without a password; keep it for throwaway containers.

How it was reproduced

Docker Desktop 4.91.0 (engine and CLI 29.8.0) on Windows 11, image postgres:18 (PostgreSQL 18.4), Compose v5.5.1. docker run --name fixes2-ops-nopw postgres:18 with no environment variables exited within a second with code 1 and the message above, in both the terminal and docker logs. The check was read in the image's own /usr/local/bin/docker-entrypoint.sh. Adding the password fixed both the docker run and the Compose version, and a third container reusing the first one's data without a password skipped the check.

Frequently asked

Why does my postgres Docker container exit immediately?

Run docker logs with the container name. If it says the database is uninitialized and the superuser password is not specified, the image refused to create a new database because POSTGRES_PASSWORD was not set. Set it and start a new container.

Does changing POSTGRES_PASSWORD change the password of an existing database?

No. The entry point reads it only when the data directory is empty and a new database is being created. For an existing volume, change the password inside PostgreSQL with ALTER USER, or remove the volume and start over if the data does not matter.

Can I run the postgres Docker image without a password?

Only by setting POSTGRES_HOST_AUTH_METHOD=trust, which lets every connection in without a password. The image itself says this is not recommended. Use it only for a throwaway local container that is not reachable from the network.

More decoded errors in the Fixes category. If your postgres:18 container exits with a different message about the data directory, see postgres:18 container exits immediately.