docker: invalid reference format: repository name (library/Hello-World) must be lowercase — Docker refuses any image name that contains a capital letter. Type the repository part of the name in lowercase (hello-world, postgres, myapp) and the same command runs.

The rule covers both directions: pulling or running an image (docker run) and naming one you build (docker build -t). Rename the image in lowercase; the name of your project folder or solution can stay as it is.

The error

docker run --rm Postgres:18 --version
docker: invalid reference format: repository name (library/Postgres) must be lowercase

Run 'docker run --help' for more information

When you build an image with a capitalised tag, Docker 29 words it slightly differently: 

docker build -t Fix4-MyApp .
ERROR: failed to build: invalid tag "Fix4-MyApp": repository name must be lowercase

Why it happens

An image reference has a fixed grammar: an optional registry host, then a repository path, then an optional :tag or @digest, as in registry.example.test/team/myapp:1.0. When you leave the registry out, Docker fills in Docker Hub and, for single-word names, the library/ namespace, which is why the message shows library/Postgres rather than what you typed. The repository path may contain only lowercase letters, digits and the separators ., _, __, - and /; capitals are not part of the grammar.

The check happens on your machine before anything is sent to a registry, so the error is instant and has nothing to do with the network, your login or whether the image exists. It most often comes from a project name copied into a script (MyApp) or from a variable like a branch name that happens to contain a capital.

The fix

docker run --rm postgres:18 --version
postgres (PostgreSQL) 18.4 (Debian 18.4-1.pgdg13+1)
docker build -q -t fix4-myapp .
sha256:53dcc96510ba2189bea5c69cdd5f74b0a19809ee454fe08b228380f385375785

Only the case of the repository name changed. The tag after the colon is more permissive (it may contain capitals), but keeping the whole reference lowercase avoids the question. In a CI script that builds the name from a variable, lowercase it first, for example with tr '[:upper:]' '[:lower:]' in a shell or .ToLowerInvariant() in PowerShell.

How it was reproduced

On Windows 11 with Docker Desktop 4.91 (client and engine 29.8.2), from PowerShell 5.1. docker run --rm Hello-World and docker run --rm Postgres:18 --version both failed with exit code 125; docker build -t Fix4-MyApp . against a one-line Dockerfile (FROM postgres:18) failed with exit code 1. The lowercase versions ran against the cached postgres:18 image (PostgreSQL 18.4) and built the image; fix4-myapp is the test's own name and was removed afterwards.

Frequently asked

Why does Docker say repository name must be lowercase?
The image reference grammar allows only lowercase letters, digits and a few separators in the repository name. Any capital letter in the name makes Docker reject it before it contacts a registry.
Can a Docker image tag contain uppercase letters?
The tag after the colon may contain capitals, but the repository name before it may not. Keeping the whole reference lowercase is the simplest rule to follow in scripts.
Why does the error mention library/ when I did not type it?
Docker expands a single-word name to the official images namespace on Docker Hub, so postgres becomes docker.io/library/postgres. The message shows that expanded repository name.

More decoded errors in the Fixes category. New to images and containers? Start with Docker explained for beginners.