Skip to content

Install and initialize Incus

This page gets a fresh Linux host ready for everyday Incus use.

Official docs:

  • Install Incus: https://linuxcontainers.org/incus/docs/main/installing/
  • Initial setup: https://linuxcontainers.org/incus/docs/main/tutorial/first_steps/
  • Zabbly Incus packages: https://github.com/zabbly/incus

Before you start

You need:

  • a Linux host with virtualization support;
  • root or sudo access;
  • enough disk space for instance images and volumes;
  • a plan for storage and networking.

Check virtualization support:

lscpu | grep -E 'Virtualization|Model name'

Check kernel and OS:

uname -a
cat /etc/os-release

Install Incus

For Debian and Ubuntu hosts, use the Zabbly Incus package repository. The official Incus installation documentation lists Zabbly as the source for up-to-date, supported packages with all Incus features.

Choose a release policy

The Stable repository tracks the latest Incus feature release and suits homelabs, development, and hosts that need current features. For long-lived production hosts, choose a Zabbly LTS branch such as lts-7.0; upstream LTS releases receive bug fixes and security updates without feature changes.

Supported hosts

Zabbly Stable currently provides packages for:

  • Debian 12 (bookworm) and Debian 13 (trixie);
  • Ubuntu 22.04 LTS (jammy), 24.04 LTS (noble), and 26.04 LTS (resolute);
  • amd64 and arm64 architectures.

Check the Zabbly Incus repository before installing on another release.

Add the Zabbly Stable repository

Run these commands as root or with sudo. First inspect the signing-key fingerprint; it must be 4EFC 5906 96CB 15B8 7C73 A3AD 82CC 8797 C838 DCFD.

curl -fsSL https://pkgs.zabbly.com/key.asc | gpg --show-keys --fingerprint
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://pkgs.zabbly.com/key.asc -o /etc/apt/keyrings/zabbly.asc

Add the repository definition:

sudo sh -c 'cat <<EOF > /etc/apt/sources.list.d/zabbly-incus-stable.sources
Enabled: yes
Types: deb
URIs: https://pkgs.zabbly.com/incus/stable
Suites: $(. /etc/os-release && echo ${VERSION_CODENAME})
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/zabbly.asc
EOF'

Install Incus:

sudo apt update
sudo apt install incus

For an LTS branch, replace stable in the URIs line with lts-6.0 or lts-7.0 and name the source file accordingly before running apt update.

Add your user to the Incus admin group

sudo usermod -aG incus-admin "$USER"
newgrp incus-admin

If newgrp is not enough, log out and log back in.

Verify access:

incus version
incus info

Initialize Incus

For a simple single-host lab, the guided initializer is best:

sudo incus admin init

Good starter choices:

  • clustering: no;
  • storage backend: dir for simplest labs, zfs if you have a dedicated disk/pool and want snapshots/clones;
  • network bridge: yes;
  • default bridge name: incusbr0;
  • IPv4 NAT: yes for easy outbound internet;
  • IPv6: only if you use it;
  • remote API access: no unless you need remote management.

Verify the result:

incus storage list
incus network list
incus profile show default

Reproducible initialization with a preseed

For repeatable new hosts, store the initialization configuration in version control and review it before applying it. This small preseed creates a dir pool and NAT bridge; use a dedicated ZFS or Btrfs pool instead for a production host that needs efficient snapshots and clones.

# incus-preseed.yaml
config:
  images.auto_update_interval: "6"
storage_pools:
  - name: default
    driver: dir
networks:
  - name: incusbr0
    type: bridge
    config:
      ipv4.address: auto
      ipv6.address: none
profiles:
  - name: default
    devices:
      root:
        path: /
        pool: default
        type: disk
      eth0:
        name: eth0
        network: incusbr0
        type: nic

Apply it only to a new host:

sudo incus admin init --preseed < incus-preseed.yaml

On an existing server, preseed data is merged with the current configuration. Back up and review the current state before changing it:

incus config show
incus network list
incus storage list
incus profile show default

Launch a first container

incus launch images:debian/13 first-container
incus list
incus shell first-container

Inside the container:

cat /etc/os-release
ip addr
exit

Clean up:

incus delete first-container --force

Launch a first VM

incus launch images:debian/trixie/cloud first-vm --vm
incus list

VMs take longer to boot than containers. Use a cloud image when you want cloud-init and the VM agent, then wait before using incus exec:

incus exec first-vm -- cloud-init status --wait
incus shell first-vm

Clean up:

incus delete first-vm --force

Enable remote API access only when needed

Bind the API only to a trusted management network or VPN, then create a one-time trust token for the client:

incus config set core.https_address=:8443
incus config trust add workstation-01

Copy the generated token to the client machine and add the remote:

incus remote add my-host <trust-token>
incus list my-host:

Security notes:

  • expose the API only on trusted networks or behind VPN/firewall rules;
  • treat a trust token as a short-lived secret and do not place it in shell history or source control;
  • use the server's externally reachable address explicitly when it is behind NAT;
  • certificate trust and explicit remotes are preferred over shared passwords.

Upgrade and rollback plan

Before an Incus upgrade, test a restore of each important instance and custom volume on another host. An Incus upgrade can apply a database schema migration when the daemon restarts; after that migration, an older Incus version might reject the database.

incus version
incus list
incus storage volume list default
sudo apt update
sudo apt install --only-upgrade incus
incus version

If an upgrade must be rolled back, do not assume that reinstalling an older package is safe. Follow the official recovery process: stop Incus, restore the database backup from /var/lib/incus/database, restore any matching external storage state, and then start the compatible daemon. Keep the tested instance and volume backups until the upgraded services pass application-level checks.

Healthy host checklist

incus info
incus list
incus storage list
incus network list
incus profile list

If these commands work, the host is ready for normal Incus administration.