Q: What is the purpose of `.dockerignore`?
A .dockerignore file lists paths that Docker leaves out of the build context, so they are never sent to the builder and cannot be copied into the image by COPY or ADD. It works much like .gitignore but applies to docker build.
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: A <strong><code>.dockerignore</code></strong> file lists paths that Docker leaves out of the build context, so they are never sent to the builder and cannot be copied into the image by <code>COPY</code> or <code>ADD</code>. It works much like <code>.gitignore</code> but applies to <code>docker build</code>. Interviewers ask about it because it affects three things at once: build speed, layer cache hits and accidental secret leakage. A good answer shows you know the context is uploaded <em>before</em> the first instruction runs, and that patterns have rules that differ from <code>.gitignore</code>.
How .dockerignore Fits Into a Build
The build context is the directory you pass to docker build, and .dockerignore filters it before anything else happens.
- Context transfer: the client packages the context and sends it to the builder; without a filter,
.git,node_modulesand build output all go too. - Location: the file sits at the root of the context. With BuildKit, a file named
<Dockerfile-name>.dockerignorenext to the Dockerfile takes precedence for that Dockerfile. - Scope: it affects
COPY,ADDand the context upload only. It does not change bind mounts atdocker runtime. - Matching: patterns are relative to the context root, a later rule overrides an earlier one, and
!re-includes a path.
Write a Practical .dockerignore
Start from what the image does not need at runtime, then verify nothing required is excluded.
# .dockerignore
.git
.gitignore
.env
.env.*
*.pem
node_modules
**/__pycache__
**/*.log
coverage/
dist/
Dockerfile
.dockerignore
docker-compose*.yml
# Re-include a file that a broader rule excluded
!README.md
- VCS and editor files:
.git,.idea,*.swpadd size and change often. - Dependencies and artifacts:
node_modules,target/,__pycache__should be rebuilt inside the image for the right OS and architecture. - Secrets:
.env,*.pem,.awsand*.tfstatemust never enter a layer, because layers are permanent and extractable. - Recursive match:
*.mdmatches only at the root; use**/*.mdto match at any depth.
Use an Allowlist and Verify the Result
The safest pattern for large repos is to exclude everything and re-include only what the build needs.
# .dockerignore (allowlist)
*
!package.json
!package-lock.json
!src/
# Debug stage: see what the builder actually received
# FROM busybox AS ctx
# COPY . /ctx
# RUN find /ctx -maxdepth 2
docker build --progress=plain --target ctx .
docker build --progress=plain -t my-app:dev .
- Allowlist style: start with
*, then add!package.json,!src. New files stay out by default. - Check context size: run
docker build --progress=plain .and read the "transferring context" line; a drop from hundreds of MB to a few MB confirms the filter works. - Inspect what landed: a throwaway stage with
COPY . /ctxandRUN find /ctxlists exactly what the builder received. - Cache effect: with
COPY . .any changed file in the context invalidates that layer, so ignoring noisy files keeps later layers cached.
Failure Modes and Edge Cases
Most .dockerignore bugs are over-exclusion or wrong pattern scope.
- Build fails with "not found": a
COPYsource is excluded. Re-include it with!pathafter the broad rule. - Rule order: the last matching pattern wins, so a
!line placed before the exclusion has no effect. - Ignoring the Dockerfile: allowed; the builder still reads it, it is just not available to
COPY. - Different from .gitignore: there is no per-directory file and no automatic recursion for patterns like
*.log.
Keep It Maintained in Production
Treat the file as part of your supply-chain hygiene.
- Review with the Dockerfile: change both in the same pull request when directory layout changes.
- Secrets belong in build secrets: use
RUN --mount=type=secretwith BuildKit, not files copied into the context. - Monorepos: use a per-Dockerfile ignore file so each service sends only its own sources.
- Defence in depth: combine it with multi-stage builds so build tooling and credentials stay out of the final image.
- .dockerignore excludes files from the build context so they are not uploaded to the builder or copied into the image.
- It speeds builds, keeps COPY layers cached and stops secrets such as .env and keys leaking into permanent layers.
- I verify it by checking the transferred context size, and in monorepos I use an allowlist plus per-Dockerfile ignore files.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Using *.md and expecting it to match nested files Patterns are anchored at the context root; nested matches need **/*.md.
- Putting a ! re-include before the broad exclusion The last matching rule wins, so the exclusion overrides the re-include.
- Relying on .dockerignore to hide secrets that are used at build time If the file is excluded the build cannot use it, and if it is copied it stays in a layer; use BuildKit secret mounts.
- Assuming it affects docker run -v bind mounts It only filters the build context; mounted host paths are fully visible to the container.