What Is a .dockerignore File?

A .dockerignore file tells Docker which files and folders should not be included in the build context.

Every time you run docker build, Docker first collects your project into a temporary bundle before sending it to the Docker daemon. Without a .dockerignore file, that bundle can contain logs, dependencies, Git history, IDE settings, temporary files, and other content that your image never needs.

A good .dockerignore file makes builds faster, images smaller, and reduces the chance of accidentally copying sensitive files into a container.

How Docker Uses a .dockerignore File

Many people assume Docker only copies files mentioned in a COPY instruction.

That isn’t quite how it works.

The build process actually looks more like this:

Project Folder
        │
        ▼
Read .dockerignore
        │
Remove excluded files
        │
        ▼
Create Build Context
        │
        ▼
Send to Docker Engine
        │
        ▼
Process Dockerfile

The filtering happens before Docker starts executing instructions inside the Dockerfile.

That means excluding unnecessary files reduces the amount of data Docker has to process from the very beginning.

Why Use a .dockerignore File?

The biggest benefits are surprisingly practical.

Faster builds

Sending a few megabytes is much quicker than sending hundreds.

Large folders like node_modules, .git, or build outputs can dramatically increase build times.

Smaller build context

Docker has fewer files to scan and hash during each build.

Even if those files never end up inside the final image, Docker still has to process them unless they’re ignored.

Better security

Projects often contain files that should never be copied into containers.

Examples include:

.env
API keys
SSH keys
local configuration files
editor settings

Ignoring these reduces the chance of exposing secrets.

Better Docker cache performance

Docker calculates checksums for files during builds.

Changing an ignored file won’t invalidate cache layers because Docker never sees it.

Where Does the File Go?

Place .dockerignore in the root of your build context. In many projects, this is the same directory as your Dockerfile.

project/

├── Dockerfile
├── .dockerignore
├── package.json
├── src/
└── README.md

When you run docker build, Docker automatically looks for .dockerignore in the build context and excludes any matching files before sending the context to the Docker daemon.

Basic Syntax

Ignoring a directory is straightforward.

node_modules/

Ignore a file:

.env

Ignore all log files:

*.log

Ignore every Markdown file:

*.md

Ignore Git history:

.git

Keeping One File

Sometimes you want to ignore everything except one file.

Docker supports exceptions using !.

*.md
!README.md

That ignores every Markdown file except README.md.

Common .dockerignore Example

# Dependencies
node_modules/

# Git
.git
.gitignore

# Logs
*.log

# Environment variables
.env
.env.local

# IDE files
.vscode/
.idea/

# macOS
.DS_Store

# Build output
dist/
build/

# Temporary files
tmp/
temp/

# Coverage
coverage/

This is a solid starting point for many JavaScript projects.

Node.js Example

A typical Node project might use:

node_modules/
npm-debug.log
yarn-error.log
pnpm-debug.log

.git
.gitignore

coverage/

dist/

.env

.vscode/

.idea/

Your Dockerfile can install dependencies itself, so copying an existing node_modules folder usually wastes space.

Python Example

Python projects often ignore:

__pycache__/

*.pyc

*.pyo

.venv/

venv/

.env

.pytest_cache/

.mypy_cache/

.git

Virtual environments belong on the host machine, not inside the container.

Java Example

target/

.gradle/

.idea/

*.class

.git

.env

Compiled artifacts can usually be recreated during the build.

Go Example

bin/

coverage.out

.git

.env

.vscode/

Common Mistakes

Ignoring files your Dockerfile needs

If your Dockerfile contains:

COPY package.json .

then package.json cannot be ignored.

Docker simply won’t be able to copy it.

Copying node_modules

Many beginners copy their local dependencies into the image.

That usually creates larger images and can introduce platform compatibility issues.

Installing dependencies during the build is normally the better option.

Forgetting .env

Local environment files often contain secrets.

They rarely belong inside production images.

Ignoring too much

If a required configuration file disappears from the build context, Docker will report that it cannot find the source during a COPY instruction.

.dockerignore vs .gitignore

These files look similar but solve different problems.

.dockerignore	.gitignore
Controls Docker build context	Controls Git tracking
Used during docker build	Used by Git
Reduces build size	Keeps repositories clean
Improves build performance	Does not control what Docker sends as the build context

Many projects use both.

Some entries overlap, but they are not interchangeable.

How Docker Processes the File

Suppose your project contains:

project/

src/
node_modules/
.git/
.env
README.md
Dockerfile

And your .dockerignore contains:

node_modules/
.git
.env

Docker only sends:

src/
README.md
Dockerfile

Everything else is filtered out before the build begins.

Best Practices

Ignore dependencies that can be installed during the build.
Ignore version control folders.
Ignore editor settings.
Ignore logs.
Ignore temporary files.
Ignore local environment files.
Keep the file under version control so everyone on the team uses the same rules.
Review the file whenever your project structure changes.

Frequently Asked Questions

Does .dockerignore reduce image size?

Indirectly.

It reduces the build context. If ignored files would otherwise have been copied into the image, the final image becomes smaller as well.

Can I have multiple .dockerignore files?

Yes.

Most projects use a single .dockerignore file in the root of the build context.

Docker also supports Dockerfile specific ignore files for projects that have multiple Dockerfiles.

Dockerfile
.dockerignore

build.Dockerfile
build.Dockerfile.dockerignore

test.Dockerfile
test.Dockerfile.dockerignore

When a Dockerfile specific ignore file exists, Docker uses it instead of the root .dockerignore for that build.

Does .dockerignore use wildcards?

Yes.

Patterns like these are supported:

*.log
*.tmp
build/

Can I include ignored files again?

Yes.

Use the ! operator.

*.md
!README.md

Should I ignore node_modules?

Usually yes.

Installing dependencies during the build is generally cleaner than copying your local installation.

Should .git be ignored?

Almost always.

Git history usually isn’t needed inside a container and can significantly increase the size of the build context.

A .dockerignore file is easy to overlook, but it has an outsized impact on Docker builds. It helps Docker process fewer files, improves caching, avoids copying unnecessary content, and keeps sensitive files out of your images.

Most projects only need a handful of rules, yet those few lines can noticeably improve build speed and produce cleaner, more predictable containers.