One of Docker’s design constraints is that it only accesses files within the build context—typically the directory you pass to docker build. If you try to include files from outside this directory, you’ll likely see an error like:
COPY failed: forbidden path outside the build context
So how can you include files outside of the build context? In this post, you’ll learn why this limitation exists, what your options are, and best practices for working around it safely.
🔍 Why the Restriction?
When you run:
docker build -t my-app .
Docker uses the . (current directory) as the build context. It uploads this directory (and its subdirectories) to the Docker daemon, where the image is built. Anything outside this context is excluded for security and performance reasons.
🚫 What You Can’t Do
You can’t do this:
COPY ../secrets/config.json /app/config.json
That file is outside the context, and Docker will throw an error.
✅ Solution 1: Move the File Into the Build Context
The simplest option is to copy or symlink the external file into your build context before the build.
Example:
cp ../config.json ./app/config.json
docker build -t my-app .
Update your Dockerfile:
COPY app/config.json /app/config.json
✅ Best for simple builds and predictable structures
✅ Solution 2: Use a Script to Copy Files Before Building
Automate the file inclusion process with a shell script:
#!/bin/bash
cp ../config.json ./tmp/
docker build -t my-app -f Dockerfile ./tmp
🔄 This keeps your source files intact while temporarily preparing a build context
✅ Solution 3: Use docker build with a Custom Context Directory
You can specify any directory as the build context, as long as it includes all the necessary files.
docker build -t my-app -f my-app/Dockerfile ../
Then in your Dockerfile (e.g., my-app/Dockerfile):
COPY my-app/src/ /app/
COPY config.json /app/config.json
🛑 Make sure sensitive files outside your project don’t accidentally get included in the context
✅ Solution 4: Use Multi-Stage Build and External Resources (Advanced)
In some cases, you can use curl, wget, or a mounted volume to fetch external files during the build (e.g., from a local server or private repo).
RUN curl http://internal-server/config.json -o /app/config.json
⚠️ This requires that the source be available over the network during build and may not be ideal for sensitive data.
🧼 Best Practices
- Keep everything needed for the image inside the build context
- Use
.dockerignoreto exclude unnecessary files (to reduce build time and image size) - Automate pre-build steps in scripts or CI pipelines
- Avoid symlinks pointing outside the build context—they won’t resolve correctly
📝 Conclusion
Docker enforces the build context boundary for good reason—but that doesn’t mean you’re stuck. By copying files, restructuring directories, or scripting pre-build steps, you can still include external files without compromising on security or workflow clarity.
🔑 Quick Summary
| Goal | Recommended Approach |
|---|---|
| Include external file | Copy into build context before build |
| Automate setup | Use shell script to prep context |
| Complex project structure | Change build context path |
| Dynamic or remote files | Use curl, wget, or mounted volume |