Incus

Incus is a next-generation system container and virtual machine manager. It manages LXC containers and QEMU virtual machines through a unified command-line interface and REST API. Instances are persistent, full-system environments with their own init system, networking, and storage, distinct from the application containers that Docker and Podman manage.

Incus originates from a community fork of LXD. In 2023, Canonical transferred LXD development exclusively to its own commercial organisation and removed the project from Linux Containers governance. The Linux Containers community forked the codebase as Incus under the LXC Project umbrella. Incus is FOSS, independently governed, and carries no commercial licensing terms. It represents the correct choice for operators who require system container infrastructure without dependency on Canonical's commercial roadmap.

🔗1. Installation

🔗Arch Linux

Incus is available in the AUR. Install with an AUR helper:

yay -S incus

Or build manually:

git clone [https://aur.archlinux.org/incus.git](https://aur.archlinux.org/incus.git)
cd incus
makepkg -si

Enable and start the service:

sudo systemctl enable --now incus
sudo systemctl enable --now incus-user

Add your user to the incus-admin group:

sudo usermod -aG incus-admin $USER

Log out and back in for group membership to take effect.

🔗Alpine Linux

apk add incus incus-client
rc-update add incusd
rc-service incusd start

🔗Ubuntu / Debian

Canonical's repositories ship LXD, the proprietary fork. Incus requires the Zabbly repository:

curl -fsSL [https://pkgs.zabbly.com/key.asc](https://pkgs.zabbly.com/key.asc) | sudo gpg --dearmor -o /etc/apt/keyrings/zabbly.gpg
echo "deb [signed-by=/etc/apt/keyrings/zabbly.gpg] [https://pkgs.zabbly.com/incus/stable](https://pkgs.zabbly.com/incus/stable) $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/zabbly-incus-stable.list
sudo apt update
sudo apt install incus
sudo adduser $USER incus-admin

🔗Verify Installation

incus --version
incus info

🔗2. Initial Configuration

Run the interactive initialisation on first use:

sudo incus admin init

The wizard configures storage pools, networking, clustering, and remote access. For a minimal single-node setup, the following answers produce a functional environment:

For production use, ZFS provides snapshots, clones, and copy-on-write storage that the dir backend does not. Install ZFS before running incus admin init:

# Arch Linux
sudo pacman -S zfs-utils
sudo modprobe zfs

🔗3. Core Architecture

🔗4. Images

Incus instances launch from images. Images are distributed via remotes. The default remotes point to Linux Containers image servers.

🔗Default Remotes

incus remote list

🔗Searching for Images

incus image list images:
incus image list images: alpine
incus image list images: arch
incus image list images: | grep -i rocky

🔗Image Properties

🔗Managing Local Images

🔗Publishing Instances as Images

Use incus publish to save a stopped container or virtual machine as a reusable image in your local image list. You can also publish from a snapshot.

# Publish a stopped container called "web-backup" as "my-website:1.0"
incus publish web-backup --alias my-website:1.0

# Publish from a snapshot
incus publish web-backup/snap0 --alias my-website:snap0

# List your published images
incus image list

Note: The source instance should be stopped unless you use --force, but forcing may produce inconsistent file-systems.

🔗Managing Image Aliases

Aliases give human-friendly names to image fingerprints. Use them to reference images in incus launch, incus copy, etc. without typing the full hash.

# List aliases you have defined locally
incus image alias list

# Create an alias "ubuntu-jammy" for image with fingerprint abc123...
incus image alias create ubuntu-jammy abc123...

# Delete an alias
incus image alias delete my-old-alias

# Rename an alias
incus image alias rename my-website my-website:stable

You can also assign aliases during incus publish, incus copy, or incus image import using the --alias flag:

incus publish my-container --alias my-container:v1
incus image copy local:my-container:v1 images: --alias public-container

🔗Building Custom Images

Incus accepts tarballs in its image format. The minimal structure requires a metadata.yaml and a root file-system tarball.

# BUILD A MINIMAL ALPINE IMAGE FOR IMPORT
mkdir -p rootfs
# populate rootfs with a base alpine system, then archive it
tar -czf rootfs.tar.gz -C rootfs .

# create metadata file
cat > metadata.yaml <<EOF
architecture: x86_64
creation_date: $(date +%s)
properties:
  description: Custom Alpine minimal
  os: Alpine
  release: edge
EOF

# bundle metadata and rootfs into an incus image tarball
tar -czf custom-alpine.tar.gz metadata.yaml rootfs.tar.gz

# import image into local cache with alias
incus image import custom-alpine.tar.gz --alias custom-alpine