Incus

On this page 7

Incus is an open-source system container and virtual machine manager for Linux that runs both LXC containers and QEMU/KVM virtual machines behind a single REST API and command-line client. In Linux virtualization, it occupies the layer above low-level runtimes: it handles images, storage, networking, clustering and access control so that administrators manage instances rather than individual processes or disk files.

Incus began in 2023 as a community fork of LXD, after Canonical moved LXD out of the Linux Containers project. It is maintained by the Linux Containers community, keeps a familiar command structure and has since diverged in features, licensing and release cadence, with long-term support releases intended for production use.

How Incus manages containers and virtual machines

Incus works as a long-running daemon that exposes a REST API over a local Unix socket and, optionally, over HTTPS for remote clients. The incus command-line tool, web interfaces and automation tools such as Terraform providers or Ansible modules all talk to the same API, which keeps behavior consistent regardless of the client.

Every workload is an instance of one of two types. A system container shares the host kernel and uses namespaces, cgroups, AppArmor or seccomp profiles and LXC underneath; a virtual machine runs its own kernel under QEMU with KVM acceleration and paravirtualized Virtio devices. Both types use the same images, profiles, storage pools and networks, so moving a workload from a container to a VM usually means changing one flag at creation time.

Containers run unprivileged by default: root inside the container is mapped to an unprivileged UID range on the host, which greatly limits the damage of a container escape.

Core building blocks of an Incus deployment

An Incus host is configured through a small set of first-class objects, each with its own API endpoint. The table below lists the objects administrators work with most often.

ObjectPurposeExample use
InstanceA container or virtual machineA Debian web server or a Windows test VM
ImageTemplate used to create instancesUbuntu, Alpine or an OCI application image
ProfileReusable set of configuration and devicesShared CPU limits and a network interface
Storage poolBackend that holds instance volumesA ZFS pool on local NVMe disks
NetworkManaged bridge or overlay networkAn OVN network spanning a cluster
ProjectIsolated namespace for objects and quotasSeparate environments for two teams
Main Incus objects

The choice of storage driver has the largest effect on performance and features, because snapshots, copies and migration depend on it.

DriverStrengthMain limitation
dirSimplest setup, no extra toolsNo efficient snapshots or quotas
ZFSFast clones, compression, reliable snapshotsNeeds ZFS kernel modules and memory
BtrfsCopy-on-write clones in the mainline kernelQuota handling is less predictable
LVMThin provisioning on block devicesFewer data management features
Ceph RBDShared storage for clusters and live migrationRequires a separate Ceph cluster
Common storage drivers

Incus overlaps with several tools in the Linux virtualization stack, but it sits at a different level of abstraction. LXC and QEMU are runtimes, libvirt is a management library mostly centered on virtual machines, and Proxmox VE is a complete distribution with a web interface.

ToolScopeKey difference from Incus
LXCLow-level container runtimeNo image server, clustering or REST API
LXDContainer and VM managerCanonical project from which Incus was forked
libvirtVirtualization API, mainly for VMsWeaker system container workflow
Proxmox VEFull virtualization distributionInstalls as an operating system with its own stack
Docker or PodmanApplication containersOne process per container instead of a full init system
Incus and neighboring tools

The most important conceptual distinction is between system containers and application containers. An Incus container boots a full init system, runs SSH, cron and multiple services, and behaves like a lightweight virtual machine, whereas an application container usually packages a single service. Recent Incus releases can also run OCI images, but that capability does not turn Incus into a replacement for container orchestration platforms.

Clustering, migration and day-to-day operations

Incus supports clustering, in which several hosts share one distributed database and appear to clients as a single API endpoint. Instances can be placed on specific members, evacuated during maintenance and moved between hosts; live migration works best for virtual machines on shared storage such as Ceph.

Routine operations follow a short and predictable command pattern. incus launch images:debian/12 web01 creates and starts a container, adding --vm creates a virtual machine, incus snapshot create captures state, and incus export writes a portable backup tarball. Limits such as limits.cpu and limits.memory apply through profiles or per instance.

For teams leaving LXD, the lxd-to-incus migration tool converts an existing installation in place, including instances, storage and networks. Testing the conversion on a non-production host first is still advisable, because storage driver and kernel differences can surface during the move.

Limitations and common mistakes

Incus is a capable platform, but several pitfalls recur in practice. The following table maps typical symptoms to their causes and fixes.

SymptomLikely causeRecommended fix
Nested Docker fails inside a containerNesting not allowedSet security.nesting=true on that instance
Slow instance creationdir storage driver copies full imagesUse ZFS, Btrfs or LVM thin pools
Files owned by odd UIDs on the hostUnprivileged ID mappingUse shifted disk devices or adjust idmaps
VM fails to startKVM unavailable or nested virtualization offEnable hardware virtualization in firmware
Frequent Incus problems

The most consequential mistake is treating privileged containers as a convenient shortcut. Setting security.privileged=true removes the UID mapping that protects the host, so it should be reserved for trusted workloads that genuinely need it, and untrusted tenants belong in virtual machines.

The short version

Incus is a tool that lets one Linux computer host many separate mini computers. Some of them are lightweight containers that share the main system’s core, and others are full virtual machines with their own operating system.

Think of an apartment building manager: one person handles the keys, the utilities and the floor plans for every apartment. Incus is that manager, so you create, copy, back up and remove these mini computers with a few short commands.

Where it makes a difference

A university computer science department needs isolated Linux environments for about 120 students each semester. Instead of buying separate servers, the administrators build a three-node Incus cluster with Ceph storage. Each student receives a system container created from a Debian image and a profile that limits it to 2 CPU cores and 4 GiB of memory.

Courses on kernel development use virtual machines instead, because students must boot and crash their own kernels. At the end of the semester, a short script deletes every project and recreates fresh instances in minutes. The department reports far less administrative work than with its previous manually maintained virtual machines, and hardware maintenance no longer interrupts classes because instances are evacuated to other cluster members.