Use files outside the default Docker build context

A local COPY source is resolved inside the selected build context, not relative to the Dockerfile. To include another directory, deliberately choose a context that contains it or supply an additional named context. A path such as ../shared does not grant arbitrary access to files outside the selected context.

Separate the Dockerfile path from the context

Suppose the project is arranged as follows:

project/
  docker/Dockerfile
  app/
  shared-libs/
  configs/

From project, build with:

docker build -f docker/Dockerfile -t myapp:dev .

The final . selects the project directory as context. The Dockerfile can then contain:

COPY shared-libs/ /opt/libs/
COPY app/ /app/

Moving the Dockerfile into a subdirectory does not change the source root for these instructions. Ensure .dockerignore does not exclude files you actually need.

Add a named context

With a builder that supports named contexts:

docker buildx build --load \
  --build-context shared=../shared-libs \
  -f Dockerfile -t myapp:dev .

Reference it in the Dockerfile:

# syntax=docker/dockerfile:1
FROM debian:bookworm-slim
COPY --from=shared / /opt/libs/

The local path is intentionally supplied by the build invocation. This keeps the main context narrow without pretending to bypass its boundary. Named contexts can also refer to supported Git or image sources. Pin external inputs when reproducibility matters, and use BuildKit secret/SSH mounts for credentials rather than putting them in context files.

--load in this example requests a local image result for a normal single-platform build. Other output choices, such as --push, serve different workflows.

Copy an artifact from another stage or image

FROM registry.example.com/team/base-builder:1.2 AS builder
RUN /usr/local/bin/build-app

FROM debian:bookworm-slim
COPY --from=builder /build/dist/ /app/

This example assumes the builder image supplies the build command and writes /build/dist. You can also use an external image as the --from source. This reads an explicitly selected image/stage filesystem; it does not make an arbitrary host directory visible.

Avoid misleading workarounds

A symlink pointing outside a local context does not make the external file contents available for copying. Likewise, COPY ../shared /app cannot escape the source root. Current BuildKit normalizes away parent-directory traversal in this form; older builders may reject it. It does not universally produce the same “forbidden path” error.

Keep contexts intentionally small and exclude irrelevant files such as .git, dependencies, logs and local secrets. Legacy builders may transfer the whole context, while BuildKit can transfer needed content more selectively; a huge context is still an unnecessary exposure and can slow processing.

FAQ

What does docker build - < Dockerfile do? Passing plain Dockerfile text as the context produces no local filesystem context. Local COPY cannot read nearby host files, but copies from explicit stages/images or other supported inputs remain possible. Passing a tar archive to stdin is different: that archive supplies a filesystem context.

Can the Dockerfile come from stdin while files come from a directory? Yes: docker build -f- . < Dockerfile selects . as the context while reading the Dockerfile separately.

How does Compose express this? Use build.context and build.dockerfile. A relative Dockerfile path is resolved from the build context; the context path itself is normally resolved from the Compose project directory. The fields have distinct roles, not unrelated path bases.

Can a named context be a Git repository? Yes, supported Git URLs can supply one. Select a reviewed revision and verify the builder supports the URL syntax you use.

See Docker build contexts, Dockerfile reference, Compose build configuration.