incus-compose

A drop-in replacement for docker compose that runs your compose.yaml on Incus - with the full Incus API available as an escape hatch when you need more than the Compose spec covers.

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.

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

Demos

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

Features

Drop-in

All the commands you know - parsing via compose-go with .env interpolation, profiles, depends_on, secrets, and configs. See the CLI reference and the compatibility matrix.

Operable

Health checks, restart policies, and depends_on: service_healthy ordering via the ic-healthd sidecar; scaling with up --scale; project isolation; live progress for pulls and lifecycle. See Health Checking.

Fast images

OCI pulls from any registry, a two-stage cache that survives down/up and dodges rate limits, and local builds via Podman/Docker. See Builds.

Air-gapped ready

pull is the only command that needs a registry, so a project pulls on a connected machine and runs on a disconnected one; --pull never makes that a guarantee rather than a hope, and the sidecar and one-off helper images point at your own mirror like any other. See Air-gapped and Proxied Installs.

Real networking

storage Bridge networks with static IPs, port publishing via proxy devices or kernel NAT, volumes with UID/GID shifting, seeded bind mounts, and per-volume pool placement.

Incus-native when you want it

Every instance, network, and volume option passes straight through via x-incus; x-incus-compose adds devices (GPU, USB, raw disk), project-wide resource limits, and healthd tuning. See Extras.

Extensions

incus-compose backup snapshots a project's data volumes into a backup project - create, list, verify, restore, and prune - so a stack's state survives the project itself, and incus-compose port-forward forwards a local TCP port into an instance, published or not. See backup and port-forward.

Quick Start

Requires Incus 7.0.1 (LTS) or 7.2+, buildah, 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

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!