incus-compose

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.

services:
  db:
    image: docker.io/postgres:18-alpine
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 2G

  web:
    image: docker.io/nginx:alpine
    depends_on:
      db: { condition: service_healthy }
    ports:
      - "8080:80"
    deploy:
      resources:
        limits:
          cpus: "1"
          memory: 512M

incus-compose up

A plain compose file, running unchanged.

• 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:

• 30-service dependency graph, 30 parallel workers
• Immich - a full photo-management stack

Features

Status: Stable.

The workflow you know:

• Familiar commands: up, down, start, stop, kill, restart, pause/unpause, list (and ps), logs, exec, cp, top, events, 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 Incus 7.0.1 (LTS) or 7.2+, 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

• Architecture - the resource-first design behind incus-compose
• 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!