A .dockerignore file keeps unnecessary paths out of a Docker build context before that context is sent to the builder. This can reduce wasted transfer and improve build speed, particularly when the builder is remote. It also helps keep accidental local files out of the build input—but it does not make a build secret-safe or automatically shrink the final image.
What does a .dockerignore file do?
A build context is the set of files Docker makes available to build instructions such as COPY and ADD. For a filesystem context, Docker processes directories recursively. A context-root .dockerignore filters matching files and directories before the context is sent to the builder. Docker Docs explains build contexts and ignore rules.
As an Amazon Associate I earn from qualifying purchases.
Without appropriate exclusions, files that are irrelevant to the build can still become part of its input. Docker says excluding unwanted files can improve build speed, especially with a remote builder. In Build Cloud, files matched by ignore rules are not transferred to the remote builder. Docker’s Build Cloud guidance describes that behavior.
Recommended Free Tools
This is a context-transfer and build-input benefit, not a promise of a smaller final image. Image contents depend on what the Dockerfile’s instructions put into the image.
What should go in .dockerignore?
Start with files the Dockerfile and build scripts do not need. Docker’s examples include .git, generated build artifacts, and package-manager directories such as node_modules. The right exclusions depend on the project: an excluded file cannot be used by later build steps as part of the context.
- Local artifacts: exclude generated output or temporary files when the build recreates them or does not use them.
- Dependency directories: exclude directories such as
node_modulesif the build installs dependencies itself rather than relying on the host copy. - Git data: excluding
.gitavoids sending repository metadata, but also means build steps cannot run Git commands such asgit rev-parseagainst that repository data. - Local secret files: excluding files such as
.envcan keep them out of the context, but is only an additional filter—not a secret-management method.
Check each exclusion against the Dockerfile and any scripts it runs. If a step needs a file, exclude it only if you provide that input another way.
Where does the ignore file go with multiple Dockerfiles?
Put the default .dockerignore at the root of the build context. When different Dockerfiles need different exclusions, Docker also supports Dockerfile-specific ignore files placed with the corresponding Dockerfile. For example, a Dockerfile named build.Dockerfile can have build.Dockerfile.dockerignore. When both apply, the Dockerfile-specific file takes precedence over the context-root file. Make sure the file placement matches the Dockerfile and context selected by the build command. Docker Docs lists the context and Dockerfile-specific ignore-file behavior.
How do .dockerignore patterns work?
Rules are newline-separated and use patterns similar to Unix shell globs. Docker disregards leading and trailing slashes in patterns. The ** pattern can match across directory levels, including zero directories. A comment begins with # in column 1. Docker also ignores the historical pattern ..
Rank #3
A leading ! creates an exception, but the last matching rule determines whether a path is included or excluded. For example:
*.log
!important.log
important.logHere, important.log is ultimately excluded because the last matching rule excludes it. Review rule order whenever an exception appears not to work.
The Dockerfile and .dockerignore are still sent to the builder because the build needs them, even if they are excluded from the context’s usable file set. Docker does not allow copying them into the image with ADD, COPY, or bind mounts. Docker Docs documents these special cases.
Does .dockerignore protect secrets?
It can keep an accidental local secret file out of the build context, but it is not a complete secret-protection mechanism. Docker says build arguments and environment variables are inappropriate for passing secrets because they persist in the final image. Use BuildKit secret mounts or SSH mounts to expose secrets to the relevant build step instead. Keep ignore rules as an extra safeguard, not as a replacement. Docker Docs explains build secrets and mounts.
Best Value
Why can’t the build find a file after you ignored it?
If a build step reports a missing file after you add an ignore rule, check whether the file is excluded from the context the Dockerfile receives. COPY and ADD can only use files available from that context; an ignored path is not available to those instructions.
- Identify the exact source path used by the failing
COPY,ADD, or build script. - Check whether a root or Dockerfile-specific ignore file has a matching rule.
- Review the full rule order, including any
!exception; the last matching rule decides. - Remove or adjust the exclusion if the build genuinely needs the file, then run the build again.
If you excluded .git, also check whether a build step expects Git metadata or runs a Git command. Docker’s build best-practices guidance notes this trade-off.
When is .dockerignore most useful?
It is useful for routine local builds because it defines which project files are relevant inputs. Its transfer benefit is most apparent when a remote builder would otherwise receive large amounts of irrelevant material; Docker describes the improvement qualitatively, not as a guaranteed percentage or fixed time saving. Docker’s best-practices documentation recommends excluding unnecessary files to improve build speed.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
