Docker Dockerignore

A Docker build starts by sending files to the Docker engine. Many beginners never notice this step, and then wonder why a tiny application takes minutes to build. The .dockerignore file controls which files travel to the engine, and it keeps builds fast, small, and safe.

What Is the Build Context

The build context is the folder you pass to the docker build command. Docker packs everything inside that folder and sends it to the build engine before it reads a single Dockerfile line.

docker build -t my-app .
                       |
                       +--> the dot means "use this folder as context"

Imagine moving to a new house. The build context is every box you load onto the truck. A truck that carries only the boxes you need arrives quickly. A truck stuffed with old furniture, broken tools, and junk takes much longer.

Why Context Size Matters

Projects collect heavy folders over time. A Node.js project holds node_modules with thousands of files. A Git repository holds a .git folder with the full history. Log files, test results, and editor settings add more weight.

Without .dockerignore            With .dockerignore
-----------------------          -----------------------
source code        2 MB          source code        2 MB
node_modules     350 MB          (ignored)
.git              80 MB          (ignored)
logs              40 MB          (ignored)
-----------------------          -----------------------
Context sent    472 MB           Context sent      2 MB

Docker prints the line "Sending build context to Docker daemon" at the start of each build. A large number on that line signals a missing .dockerignore file.

Creating a Dockerignore File

Create a plain text file named .dockerignore in the same folder as your Dockerfile. Each line holds one pattern, and Docker skips every file that matches.

node_modules
.git
.gitignore
*.log
*.md
tmp/
.env
Dockerfile
docker-compose.yml

Pattern Rules

Pattern           Meaning
---------------   ------------------------------------------
*.log             any file ending in .log in the root folder
**/*.log          any .log file in any subfolder
tmp/              the tmp folder and everything inside it
!important.md     an exception: keep this file
# comment         a comment line, ignored by Docker

The exclamation mark creates exceptions. Exclude all markdown files with *.md and add !README.md on the next line to keep the readme.

Benefits You Gain

Faster Builds

Less data moves to the engine, so the build starts sooner.

Better Cache Use

A COPY instruction invalidates its cache when any copied file changes. Ignoring log files and temporary folders stops pointless rebuilds.

Safer Images

Files like .env, private keys, and passwords must never land inside an image. Anyone who pulls the image can read those files. Listing them in .dockerignore blocks the mistake before it happens.

Smaller Images

A command such as COPY . /app copies every file that survives the ignore filter. Fewer files in the context mean a smaller final image.

A Complete Example

Project folder
  app.py
  requirements.txt
  Dockerfile
  .dockerignore
  venv/            (local virtual environment, 200 MB)
  __pycache__/
  .env             (secret keys)

.dockerignore content
  venv/
  __pycache__/
  .env

The build now sends only app.py, requirements.txt, and the Dockerfile. The virtual environment stays behind because the image installs its own packages from requirements.txt.

Allowlist Strategy

Security-focused teams flip the logic. They ignore everything and then name the files they want.

*
!app.py
!requirements.txt
!src/

This approach protects against new junk files that appear later, because nothing enters the context unless someone adds it on purpose.

Common Mistakes

• Placing .dockerignore in the wrong folder. It must sit at the root of the build context.
• Ignoring a file that a COPY instruction needs, which causes a "file not found" error.
• Forgetting to ignore .env files that hold credentials.

Add a .dockerignore file to every project on day one. The habit costs a minute and saves hours.

Real-World Scenario

A student builds a Node.js image on a school laptop. The project folder includes a node_modules folder with 40,000 files and a Git history from three months of experiments. The first build takes four minutes, and most of that time passes while Docker sends the context. The student adds a .dockerignore file with five lines. The next build starts in seconds and produces an image 300 MB lighter.

A company repeats this lesson at a larger scale. A pipeline that builds fifty images a day saves hours of machine time each week after the team adds ignore files to every repository. Smaller contexts also reduce network traffic between build servers.