Docker fails when the build context exceeds size limits. This happens when large files or directories like node_modules, .git, or logs are inadvertently included. Create a .dockerignore file to exclude unnecessary files.
When you run `docker build`, Docker packages all files in your build directory (the "build context") and sends them to the Docker daemon. The "context too large" error occurs when this context exceeds the daemon's configured size limit or available memory. The build context includes every file and subdirectory in your Dockerfile's directory by default. This means version control folders (`.git`), dependency directories (`node_modules`, `vendor`), build artifacts, logs, and temporary files all get packaged and transferred—even if your Dockerfile never uses them. This error is common in projects with large repositories, many dependencies, or when running Docker builds from a directory containing unrelated large files. The solution is to exclude unnecessary files using a `.dockerignore` file.
Before making changes, measure your current build context size:
# See what Docker reports as context size
docker build . 2>&1 | head -5
# Check directory size manually
du -sh .
# Find the largest directories
du -h --max-depth=1 . | sort -hr | head -10This helps identify which directories are contributing most to the context size.
Create a .dockerignore file in your project root (same directory as your Dockerfile):
touch .dockerignoreThis file uses the same syntax as .gitignore and tells Docker which files to exclude from the build context.
Add these common patterns to your .dockerignore:
# Version control
.git
.gitignore
.svn
# Dependencies (will be installed fresh in container)
node_modules
vendor
.venv
__pycache__
# Build artifacts
dist
build
*.egg-info
# IDE and editor files
.idea
.vscode
*.swp
*.swo
.DS_Store
# Logs and temp files
*.log
logs
tmp
temp
# Docker files (not needed in context)
Dockerfile
docker-compose*.yml
.dockerignore
# CI/CD
.github
.gitlab-ci.yml
.travis.yml
# Testing
coverage
.nyc_output
*.test.js
*.spec.js
# Documentation
docs
*.md
README*
# Environment and secrets
.env*
*.pem
*.keyIdentify and exclude files specific to your project:
# Find large files in your project
find . -type f -size +10M -exec ls -lh {} \;
# Find large directories
du -h --max-depth=2 . | sort -hr | head -20Add any large files or directories to your .dockerignore:
# Project-specific
data/
*.sql
*.dump
*.tar.gz
backups/
.vagrant/Ensure your Dockerfile doesn't explicitly copy files you've excluded. If you need certain files, use exceptions:
# In .dockerignore - exclude all markdown except README
*.md
!README.md
# Exclude all in docs except API docs
docs/*
!docs/api/The ! prefix creates exceptions to exclusion rules. Rules are processed top-to-bottom, so place exceptions after the exclusion.
After creating your .dockerignore, verify the improvement:
# Rebuild and check context size
docker build . 2>&1 | head -5
# Compare with previous size
# You should see a significant reductionA well-configured .dockerignore can reduce context from gigabytes to megabytes.
For complex projects, consider building from a subdirectory:
# Create a dedicated docker build directory
mkdir -p docker-build
cp Dockerfile docker-build/
cp -r src docker-build/
cp package.json docker-build/
cd docker-build && docker build -t myapp .Or specify the build context explicitly:
# Build with Dockerfile in current dir, but context from subdirectory
docker build -f ./Dockerfile ./srcIf context is still large, debug what's being included:
# Use docker-show-context tool
docker build -t docker-show-context https://github.com/pwaller/docker-show-context.git
docker run -v ${PWD}:/context docker-show-context
# Or simulate with tar (shows what would be sent)
tar -cvf - --exclude-from=.dockerignore . | wc -cThis reveals exactly which files are included in your build context.
### Multi-Dockerfile Projects
If you have multiple Dockerfiles, you can create specific ignore files for each:
- Dockerfile.dev.dockerignore for docker build -f Dockerfile.dev
- Dockerfile.prod.dockerignore for docker build -f Dockerfile.prod
Docker automatically looks for <dockerfile-name>.dockerignore before falling back to .dockerignore.
### BuildKit Considerations
Docker BuildKit (enabled by default in newer Docker versions) handles context more efficiently, but .dockerignore is still essential:
# Force BuildKit for better performance
DOCKER_BUILDKIT=1 docker build .### Security Implications
Always exclude sensitive files from build context, even if your Dockerfile doesn't copy them. The entire context is sent to the daemon, and in remote build scenarios, this could expose secrets:
# Always exclude these
.env*
*.pem
*.key
.aws/
.ssh/
credentials*### CI/CD Optimization
In CI pipelines, the build context transfer can be a bottleneck. Consider:
1. Using multi-stage builds to reduce final image size
2. Caching dependency layers separately
3. Using .dockerignore aggressively to minimize transfer time
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub