nerdctl compose
`nerdctl compose` brings Docker Compose functionality to containerd. Run multi-container applications with the same docker-compose.yml files you already know, powered by the lightweight containerd runtime.
`nerdctl compose` is a built-in feature of nerdctl that provides Docker Compose functionality for containerd. It allows you to define and run multi-container applications using the same `docker-compose.yml` files you use with Docker Compose, but powered by containerd instead of the Docker Engine.
This is a game-changer for developers who want to use containerd but still need the convenience of Compose for local development. With `nerdctl compose`, you get the same developer experience—defining services, networks, volumes, and dependencies—while leveraging containerd's lightweight and efficient runtime.
nerdctl includes compose support out of the box. No separate installation is needed.
# Install nerdctl (Linux)
curl -L https://github.com/containerd/nerdctl/releases/download/v1.7.0/nerdctl-1.7.0-linux-amd64.tar.gz -o nerdctl.tar.gz
sudo tar Cxzvf /usr/local/bin nerdctl.tar.gz
# macOS
brew install nerdctl
# Windows
choco install nerdctl
# Verify compose support
nerdctl compose version
nerdctl compose --help
Here are common compose file patterns that work with nerdctl compose:
# Basic web app with database
version: '3.8'
services:
web:
image: nginx:alpine
ports:
- "80:80"
networks:
- appnet
app:
build: .
depends_on:
- db
environment:
- DB_HOST=db
networks:
- appnet
db:
image: postgres:15-alpine
environment:
POSTGRES_PASSWORD: secret
volumes:
- pgdata:/var/lib/postgresql/data
networks:
- appnet
volumes:
pgdata:
networks:
appnet:
driver: bridge
Most Docker Compose commands work the same way with `nerdctl compose`:
nerdctl compose up
Start services (foreground)
nerdctl compose up -d
Start services (background)
nerdctl compose down
Stop and remove containers
nerdctl compose ps
List services
nerdctl compose logs
View logs
nerdctl compose build
Build images
nerdctl compose pull
Pull images
nerdctl compose restart
Restart services
nerdctl compose stop
Stop services
nerdctl compose start
Start services
nerdctl compose exec
Execute command in service
nerdctl compose config
Validate compose file
# Typical development workflow
nerdctl compose up -d # Start in background
nerdctl compose logs -f app # Watch app logs
nerdctl compose exec app sh # Shell into app container
nerdctl compose down -v # Stop and remove volumes
# Run specific services only
nerdctl compose up -d web db
# Scale a service
nerdctl compose up -d --scale web=3
# Build and start with no cache
nerdctl compose build --no-cache
nerdctl compose up -d
# View service logs with filtering
nerdctl compose logs -f --tail 50 web
# Run one-off commands
nerdctl compose run --rm app npm test
# Use alternate compose file
nerdctl compose -f docker-compose.prod.yml up -d
# Override with multiple files
nerdctl compose -f docker-compose.yml -f docker-compose.override.yml up -d
nerdctl compose can build images from Dockerfiles, just like Docker Compose. It uses BuildKit under the hood for fast, efficient builds.
# Build all services with build context
nerdctl compose build
# Build specific service
nerdctl compose build app
# Build without cache
nerdctl compose build --no-cache
# Build and start
nerdctl compose up -d --build
# Build with specific arguments
nerdctl compose build --build-arg NODE_VERSION=18 app
Here's a complete development workflow using nerdctl compose for a Node.js application with a database:
# docker-compose.dev.yml
version: '3.8'
services:
app:
build:
context: .
target: development
ports:
- "3000:3000"
- "9229:9229" # Debug port
volumes:
- .:/app
- /app/node_modules
environment:
- NODE_ENV=development
- DB_HOST=postgres
depends_on:
- postgres
command: npm run dev
postgres:
image: postgres:15-alpine
environment:
POSTGRES_USER: devuser
POSTGRES_PASSWORD: devpass
POSTGRES_DB: app_dev
volumes:
- pgdata:/var/lib/postgresql/data
ports:
- "5432:5432"
adminer:
image: adminer
ports:
- "8080:8080"
volumes:
pgdata:
# Development workflow
nerdctl compose -f docker-compose.dev.yml up -d
nerdctl compose -f docker-compose.dev.yml logs -f app
nerdctl compose -f docker-compose.dev.yml exec app npm run test
nerdctl compose -f docker-compose.dev.yml down -v
nerdctl compose supports the same environment variable features as Docker Compose.
# .env file (auto-loaded)
DB_PASSWORD=secret
NODE_ENV=production
# docker-compose.yml
version: '3.8'
services:
app:
image: myapp:${TAG:-latest}
environment:
- DB_PASSWORD=${DB_PASSWORD}
- NODE_ENV=${NODE_ENV:-development}
env_file:
- .env.production
# Use custom env file
nerdctl compose --env-file .env.production up -d
# Validate compose file
nerdctl compose config
# Check service status
nerdctl compose ps
# View detailed logs
nerdctl compose logs --no-color
# Check container details
nerdctl compose exec app env
nerdctl compose exec app ls -la
# Reset everything
nerdctl compose down -v
nerdctl compose up -d
- Compatibility: Most docker-compose.yml files work without changes.
- Performance: nerdctl compose is generally faster and lighter.
- Footprint: Uses containerd instead of Docker Engine, reducing resource usage.
- Rootless: Supports rootless mode for enhanced security.
- BuildKit: Uses BuildKit for faster image building.
nerdctl compose brings the convenience of Docker Compose to containerd. Start building multi-container applications today with a faster, lighter runtime.