Skip to main content

Using Local Images with Docker Compose

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.

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