Docker Compose: Use a Local Image Instead of Pulling (2026)

To make Docker Compose use a local image instead of pulling one, reference the image tag and add pull_policy: never — or let Compose build the image itself with build:. Both keep Compose away from Docker Hub. This guide covers both methods, the pull_policy values, and the errors you hit when the local image is not found.

Method 1: Build Context (Recommended)

The best way to use local code is to let Compose build it for you.

services:
  my-app:
    build: ./my-app-source  # Path to directory containing Dockerfile
    image: my-custom-image:local # Optional: tags the built image

When you run docker compose up --build, it builds the image from source and uses it immediately.

Method 2: image without build

If you have already built an image using docker build -t my-local-image:v1 ., you can refer to it directly:

services:
  worker:
    image: my-local-image:v1
    pull_policy: never  # Important!

The pull_policy flag

• pull_policy: never: Tells Compose to only look for the image locally and fail if not found. This prevents it from trying to pull from Docker Hub.
• pull_policy: if_not_present (Default): Uses local image if available, otherwise pulls.
• pull_policy: always: Always tries to pull.

pull_policy needs Compose v2 (the docker compose plugin). The legacy docker-compose v1 binary does not support it — there, pin the tag to something that does not exist upstream (for example my-image:local) so a pull cannot succeed.

---

build or image: which one do you want?

Both stop Compose from pulling, but they solve different problems.

You want	Use	What happens
Compose to build from your source	build: ./path	Image is rebuilt on --build, always in sync with your code
Reuse an image you already built by hand	image: tag + pull_policy: never	Nothing is built; the cached image is used as-is
Build once, tag it, reuse later	build: and image: together	Compose builds it and stores it under your tag

Rule of thumb: if the Dockerfile lives next to the Compose file, use build:. If the image came from somewhere else (a CI job, docker save/docker load, another repo), use image: with pull_policy: never.

Stop Compose from pulling an image

docker compose up pulls whenever the tag is not in the local cache. Three ways to prevent it:

1. pull_policy: never on the service — the explicit, per-service answer.
2. docker compose up --pull never — same thing as a one-off flag, no file change.
3. Use a tag that cannot exist upstream, like my-app:local. A pull would fail anyway, so keep the image cached locally.

Check what Docker already has with docker images. If your tag is not in that list, Compose has nothing to use and will try the registry.

Rebuilding after a code change

docker compose up --build        # rebuild images, then start
docker compose build my-app      # rebuild one service only
docker compose up --build --force-recreate

docker compose up on its own will not rebuild — it reuses the existing image even if your source changed. That is the most common reason "my change did not show up."

Common Issues

"manifest for ... not found"

If you see this error, it means Compose tried to pull the image and failed. Ensure you set pull_policy: never or if_not_present and that the image actually exists in your local cache (docker images).

Sharing Local Images

Local images only work on your machine. To share your Compose file with a team or deploy to a server (like Hostim), you must:

1. Push the image to a registry (Docker Hub, GHCR).
2. Or use the build context so the destination machine can build it too.

---

Deploying to Hostim?

Hostim supports both methods: we can build your Dockerfile for you, or pull your pre-built images from any registry.

Start Deployment

Frequently asked questions

How do I make Docker Compose use a local image instead of pulling?

Reference the image by its tag and add 'pull_policy: never' to the service. Compose will then only look in your local image cache and fail with an error instead of contacting Docker Hub. You can also pass '--pull never' to 'docker compose up' as a one-off.

How do I tell Docker Compose to use a locally built image?

Two options. Either use 'build:' to let Compose build the image from a Dockerfile next to your Compose file, or run 'docker build -t my-image:tag .' first and reference it with 'image: my-image:tag' plus 'pull_policy: never'.

What is the default pull_policy in Docker Compose?

'if_not_present' (also called 'missing'). Compose uses a local image if one is already cached and pulls from the registry only when the tag is missing.

Why do I get 'manifest for ... not found' with a local image?

Compose could not find the image locally, so it tried to pull it and the tag does not exist in the registry. Run 'docker images' to confirm the exact tag is cached, then add 'pull_policy: never' so Compose stops reaching for the registry.

Does docker compose up rebuild my image after a code change?

No. 'docker compose up' reuses the existing image. Run 'docker compose up --build' (or 'docker compose build <service>') to rebuild after changing your source.

Can I use a local image on a remote server?

Not directly — a local image only exists in the cache of the machine that built it. To deploy elsewhere, push the image to a registry such as Docker Hub or GHCR, or use a 'build:' context so the target machine builds it from source.