Introduction

Yes, a Dockerfile can use a local image as its base image. The key requirement is that the image name referenced by FROM must exist in the image store visible to the builder that is performing the build.

The Basic Pattern

If you already have an image on your machine, tag it and reference that tag in the Dockerfile. Docker does not care whether the image originally came from Docker Hub, a private registry, or a previous local build.

First, create or inspect the base image:

docker images

Assume the local image is named my-base:dev. Then your Dockerfile can use it directly:

1FROM my-base:dev
2
3WORKDIR /app
4COPY . .
5RUN python3 -m compileall .
6CMD ["python3", "main.py"]

And then build the derived image:

docker build -t my-app:dev .

If my-base:dev exists locally for the active builder, Docker uses it without pulling from a registry.

Build the Base Image First

A common workflow is to build a reusable base image in one directory and then build the application image on top of it in another directory.

Example base image:

1# base/Dockerfile
2FROM python:3.12-slim
3RUN apt-get update \
4    && apt-get install -y --no-install-recommends curl \
5    && rm -rf /var/lib/apt/lists/*

Build and tag it:

docker build -t my-base:dev ./base

Then use that tag from the app Dockerfile:

1# app/Dockerfile
2FROM my-base:dev
3COPY requirements.txt .
4RUN pip install --no-cache-dir -r requirements.txt
5COPY . .
6CMD ["python3", "main.py"]

This is a clean way to share a common toolchain across multiple local images.

Understand Which Builder Is Doing the Work

This is the part that trips people up. With plain docker build, the local Docker daemon usually sees your local images. With buildx, remote builders, or CI systems, the builder might run in a different environment where your local image is not available.

For example, if you build the base image with one builder and the final image with another, the second builder may try to pull my-base:dev from a registry because it cannot see your local daemon cache.

A few ways to handle that are:

• use the same local builder for both images
• load the base image into the local daemon with --load
• push the base image to a registry and reference that registry tag explicitly

docker buildx build --load -t my-base:dev ./base

If the build environment is remote, using a local-only base image usually stops being practical. In that case, a private registry is the better solution.

Tagging Matters More Than Location

Dockerfile syntax does not have a special local: scheme. The FROM instruction just takes an image reference. Whether that reference resolves locally or remotely depends on what the builder can find.

That means this is valid:

FROM custom-ubuntu:secure

But this is not a special local-image syntax:

# not a special feature, just an ordinary image reference
FROM custom-ubuntu:secure

The resolution rules are normal image lookup rules, not a separate Dockerfile feature for local assets.

Common Pitfalls

The most common mistake is assuming every Docker builder sees the same local images. That is false once buildx, remote builders, or CI agents enter the picture.

Another mistake is forgetting the tag. If you write FROM my-base:dev but only built my-base:latest, Docker will not match them.

People also sometimes expect COPY to pull a host file system into the FROM line. That is not how image inheritance works. FROM only references an image, not a directory on disk.

Finally, if Docker tries to pull the image instead of using the local copy, check whether the builder context changed or the local image name was mistyped.

Summary

• A Dockerfile can use a local image directly through FROM image:tag.
• The referenced tag must exist in the image store visible to the active builder.
• Build the base image first, tag it clearly, then reference that tag from derived images.
• 'buildx and remote builders may not see images from your local daemon.'
• If the build environment is not local, push the base image to a registry instead.