incus-compose

Use existing docker-compose.yml files 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

flowchart LR
    subgraph F["your files"]
        direction TB
        CY[compose.yaml]
        CI["compose.incus.yaml<br/>optional Incus overrides"]
        DE[.env]
    end
 
    F --> IC[incus-compose]
    IC --> P
 
    subgraph P["one Incus project per compose project"]
        direction TB
        IMG["images<br/>copied from the shared cache"]
        NET["bridge networks<br/>real IPs and DNS"]
        VOL["storage volumes<br/>UID/GID shifted"]
        INST["instances<br/>web-1, db-1, ..."]
        HD["ic-healthd<br/>healthchecks and restarts"]
    end

New to Incus? See Why Incus? for what the platform brings over a classic OCI engine setup.

Demos#

Recorded during the beta - the workflow is unchanged in current releases:

Features#

Status: Stable.

The workflow you know:

Familiar commands: up, down, start, stop, restart, list (and ps), logs, exec, config, plus build, healthd, incus (pass-through), and self-update
Compose project parsing via compose-go: .env interpolation, profiles, depends_on, secrets, and configs
Automatic compose.incus.yaml override file - keep the upstream compose file untouched and put Incus tuning next to it doc
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_healthy ordering via the ic-healthd sidecar doc
Service scaling with up --scale and 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.devices doc
The full Incus API as an escape hatch: any instance, network, or volume option passes straight through via x-incus doc

Quick Start#

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/bin

Or 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.

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 down

Quick Links#

Getting Started - install and run your first project
Compose Compatibility - what works and what does not
Changelog - what changed since 0.0.1-beta1

Support and community#

The following channels are available for questions and discussion around incus-compose.

Bug reports#

You can file bug reports and feature requests at: https://github.com/lxc/incus-compose/issues/new

Community support#

Community support is handled at: https://discuss.linuxcontainers.org

Contributing#

Fixes and new features are greatly appreciated. Make sure to read our contributing guidelines first!

Updated Aug 13, 2026