When building Docker images, a common issue developers face is trying to add or copy files from outside the Docker build context (e.g., from a parent directory). You may try something like this in your Dockerfile:
COPY ../config.yml /app/config.yml
But you’ll quickly run into this error:
COPY failed: forbidden path outside the build context
Why does this happen, and how can you fix it? Let’s explore.
1️⃣ Why Can’t Docker Copy Files from a Parent Directory?
When you run:
docker build -t myapp .
The . (dot) specifies the build context—the directory (and its children) that Docker has access to when building an image.
For security and consistency reasons, Docker does not allow accessing files outside the build context. That’s why trying to copy from ../ fails.
2️⃣ Solutions to Add Files from a Parent Directory
✅ Option 1: Adjust Your Build Context
The simplest fix is to change the build context when running docker build.
If your project structure looks like this:
project/
config.yml
app/
Dockerfile
Instead of running:
cd app
docker build -t myapp .
Run:
cd project
docker build -t myapp -f app/Dockerfile .
Now you can copy the parent file:
COPY config.yml /app/config.yml
✅ Option 2: Restructure Your Project
Another approach is to place all necessary files inside the same directory as your Dockerfile.
For example, move config.yml into app/ or create a docker/ directory to keep everything together.
✅ Option 3: Use a Symlink (Not Recommended)
You might think of creating a symlink to point to a parent directory file. However, Docker resolves symlinks within the context, and it will still block paths outside. This usually won’t work and is considered bad practice.
✅ Option 4: Copy Files at Build Time (Advanced)
If you cannot restructure your project, you can dynamically copy files before building:
cp ../config.yml ./app/
docker build -t myapp ./app
This adds the needed file inside the build context before building.
✅ Option 5: Use Docker BuildKit with --mount (Experimental)
With Docker BuildKit, you can temporarily mount files from outside the build context during the build process:
# syntax=docker/dockerfile:1.2
FROM alpine
RUN --mount=type=bind,source=../config.yml,target=/config.yml \
cp /config.yml /app/config.yml
Then build with BuildKit enabled:
DOCKER_BUILDKIT=1 docker build -t myapp .
This avoids copying files permanently into your build context.
📌 Summary
Docker restricts access to files outside the build context for security and reproducibility. If you need to add a file from a parent directory:
- ✅ Set the build context higher (preferred solution)
- ✅ Restructure your project
- ✅ Pre-copy files before building
- ✅ Use BuildKit for advanced scenarios
By managing your build context correctly, you’ll avoid the common forbidden path outside the build context error and keep your Docker builds clean and predictable.