.dockerignore

Docker hub

A file in the build context directory that lists files and directories Docker should exclude when sending the build context to the daemon. Excluding node_modules, .git, and test fixtures reduces build context from gigabytes to megabytes.

.dockerignore — Keeping Your Build Context Fast and Safe

What Is .dockerignore in Simple Terms?

When you run docker build ., Docker sends your entire project directory to the Docker daemon before executing a single Dockerfile instruction. Without .dockerignore, that includes your 500MB node_modules folder, your .git history, your .env secrets file, and every test fixture and build artifact you have ever created. All of it gets sent over the network before the build even starts.

.dockerignore tells Docker which files to exclude. It uses the same syntax as .gitignore.

TEXT

Without .dockerignore:
  Sending build context to Docker daemon  890.5MB
  (890MB sent before build starts)
 
With .dockerignore:
  Sending build context to Docker daemon  2.3MB
  (386x reduction — build starts immediately)

Production .dockerignore Template

Bash

# .dockerignore
 
# Dependencies — always install inside container, never copy from host
node_modules/
npm-debug.log
.npm/
.yarn/
__pycache__/
*.pyc
venv/
.venv/
 
# Build output — built inside container via multi-stage
dist/
build/
.next/
out/
target/
 
# Version control
.git/
.gitignore
.gitattributes
 
# Environment and secrets — NEVER in images
.env
.env.*
!.env.example
*.pem
*.key
*.crt
 
# Development tools
.vscode/
.idea/
*.swp
*.swo
 
# Tests
coverage/
.nyc_output/
__tests__/
*.test.ts
*.spec.ts
*.test.js
*.spec.js
 
# Docker files themselves
Dockerfile
Dockerfile.*
docker-compose.yml
docker-compose.*.yml
 
# Documentation
docs/
*.md
!README.md
 
# macOS
.DS_Store
 
# Logs
*.log
logs/

Measuring the Impact

Bash

# Check build context size before adding .dockerignore
docker build .
# Sending build context to Docker daemon  890.5MB
 
# Add .dockerignore, rebuild
docker build .
# Sending build context to Docker daemon  2.3MB
 
# 386x reduction — instant improvement with zero other changes

Important Distinction

TEXT

.dockerignore controls what is SENT TO THE DAEMON
Dockerfile COPY controls what goes INTO THE IMAGE
 
You need both:
  .dockerignore: excludes node_modules from context (build speed)
  COPY src/ /app/src/: copies only src, not everything (image cleanliness)
 
If a file is in .dockerignore:
  It is NOT sent to daemon
  COPY instructions cannot access it
  It cannot end up in the image

Tip
Create .dockerignore as the very first file in every new project — before writing any Dockerfile. It is much easier to add it at the start than to discover 6 months later that your API keys are in every image you have ever pushed to your registry.

Common Mistake
Not adding .env to .dockerignore. Your .env file contains real credentials. If it gets sent to the daemon and a COPY . . instruction runs, it ends up baked into an image layer permanently — visible to anyone who runs docker history on the image.

Frequently Asked Questions

Does .dockerignore actually speed up the build, or just keep the image smaller?

Both, but the build-context effect is the one people miss. Before Docker even runs the first instruction, it tars up the entire build directory and streams it to the daemon. If node_modules or a .git history sits in there uncached, that transfer alone can add tens of seconds before the build logic starts, especially over a remote Docker context or in CI where the daemon isn't local.

What's a common mistake teams make with .dockerignore?

Writing it once and forgetting it as the project grows — new build artifacts (dist/, coverage/, .next/) get added over time and nobody updates the ignore file, so context size creeps back up. Also worth knowing: .dockerignore only excludes files from being sent to the daemon, it doesn't affect files already COPYed by an earlier layer, so exclude patterns need to match your actual COPY instructions.