Bring the familiar Docker Compose workflow to Incus. incus-compose implements the Compose specification for the Incus ecosystem, allowing you to define and run multi-container applications using the compose.yaml files you already know.
Recorded during the beta - the workflow is unchanged in current releases:
Incus provides powerful system containers and virtual machines with superior security and isolation, but lacks the declarative multi-container orchestration that Docker Compose offers. This tool bridges that gap:
- Use existing
docker-compose.ymlfiles with Incus containers - Leverage Incus's native OCI registry support for image pulling
- Run Docker/OCI images directly from registries
- Manage complex multi-container applications with familiar commands
- Benefit from Incus's resource efficiency and security model
New to Incus? See Why Incus? for what the platform brings over a classic OCI engine setup.
Status: Stable.
The workflow you know:
- Familiar commands:
up,down,start,stop,restart,list(andps),logs,exec,config, plusbuild,healthd,incus(pass-through), andself-update - Compose project parsing via compose-go:
.envinterpolation, profiles,depends_on, secrets, and configs - Automatic
compose.incus.yamloverride file - keep the upstream compose file untouched and put Incus tuning next to it doc - Windows and macOS clients: No Docker Desktop, no WSL, no local Linux VM.
incus-composeand theincusclient are portable Go binaries — from a Windows or macOS desktop you drive a remote Incus host over HTTPS and manage OCI containers, LXC system containers, and VMs directly. See Installing on Windows. - Configuration via
INCUS_COMPOSE_*environment variables for every flag, with a configurable parallel worker count doc
Images:
- OCI image pulling from docker.io, ghcr.io, and other registries
- Two-stage image cache in a dedicated Incus project (survives
down/up, avoids registry rate limits) - Local image building via Podman/Docker doc
Networking:
- Bridge networks with automatic name sanitization; external pre-existing networks
- Static IPv4/IPv6 addresses with automatic DHCP ranges doc
- Port forwarding via proxy devices or kernel NAT mode doc
Storage:
- Storage volumes with UID/GID shifting; bind mounts (pass-through by default, optional seeding) doc
- Per-volume storage pool placement - pin a database volume to your fast SSD pool doc
Operations:
- Health checks, restart policies, and
depends_on: service_healthyordering via theic-healthdsidecar doc - Service scaling with
up --scaleand orphan pruning - Incus project isolation
- Resource limits and other advanced compose features (
shm_size,container_name, etc.)
Beyond any OCI engine:
- Project-wide resource limits - cap CPU and memory for the entire stack, enforced by Incus doc
- GPU, USB, and raw disk passthrough per service via
x-incus-compose.devicesdoc - The full Incus API as an escape hatch: any instance, network, or volume option passes straight through via
x-incusdoc
Requires podman or docker for image building and an Incus https remote (needed for healthchecking) with OCI registries added.
See Getting Started for the full setup walkthrough.
Install the latest release:
curl -sSfL https://raw.githubusercontent.com/lxc/incus-compose/main/install.sh | sh -s -- -b ~/.local/binOr grab a prebuilt archive from the Releases Page.
On Arch Linux, install incus-compose-bin
(or incus-compose-git for builds from main)
from the AUR - maintained by @neitsab and @jochumdev.
Then point it at your existing compose.yaml:
# Start services
incus-compose up -d
# View logs
incus-compose logs -f
# List running services
incus-compose list
# Stop and remove
incus-compose downAll docs: docs.incus-compose.org
- Getting Started - Install and run your first compose project
- CLI Reference - Commands and options
- Compose Compatibility - What works and what doesn't
- Architecture - the resource-first design behind incus-compose
- Why Incus? - Benefits over Docker
- Changelog - what changed since 0.0.1-beta1
Descriptions are in our docs while the files are in examples.
The following channels are available for questions and discussion around incus-compose.
You can file bug reports and feature requests at: https://github.com/lxc/incus-compose/issues/new
Community support is handled at: https://discuss.linuxcontainers.org
Fixes and new features are greatly appreciated. Make sure to read our contributing guidelines first!
This project is inspired by @bketelsen.
Some components are adapted from docker compose.
The install.sh script is adapted from golangci-lint.
This project uses AI tools as development aids (drafting, iteration, reviews, tests, and documentation). Architecture, constraints, and final code decisions are owned by the human committers.
Earlier development was on Gitlab.