Skip to main content

Docker Compose: Use a Local Image Without a Registry

Sometimes you want to run a service using an image you built manually on your machine, without pushing it to Docker Hub or a private registry.

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.

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.

FAQ​

Can Docker Compose use a local image without pulling?​

Yes. Set pull_policy: never on the service. Compose will only look for the image in your local cache and fail if it is not there, instead of trying to pull from Docker Hub.

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, 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 cached, otherwise it pulls from the registry.

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

Compose tried to pull the image because it could not find it locally. Check docker images to confirm the tag exists, and add pull_policy: never.

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