Skip to content

Incus

Incus is a modern system container and virtual machine manager. It lets you run Linux system containers and full VMs with one consistent CLI, API, image workflow, storage model, and network model.

Think of Incus as a practical homelab and infrastructure tool for creating small servers quickly:

  • lightweight Linux containers for services that can safely share the host kernel;
  • full virtual machines when you need stronger isolation, custom kernels, Windows, or production-like behavior;
  • images, profiles, projects, networks, storage pools, snapshots, backups, and remotes from the same incus command.

Incus is the community-led continuation of the LXD technology stack under the Linux Containers project.

Official resources

Use the official documentation as the source of truth for version-specific syntax.

  • Incus project page: https://linuxcontainers.org/incus/
  • Incus documentation: https://linuxcontainers.org/incus/docs/main/
  • Getting started: https://linuxcontainers.org/incus/docs/main/tutorial/first_steps/
  • Containers and VMs: https://linuxcontainers.org/incus/docs/main/explanation/containers_and_vms/
  • How-to guides: https://linuxcontainers.org/incus/docs/main/howto/
  • Image server: https://images.linuxcontainers.org/
  • GitHub repository: https://github.com/lxc/incus

Why use Incus?

Use Incus when you want fast, repeatable infrastructure without immediately reaching for a full Kubernetes cluster or a cloud provider.

Good fits:

  • homelab services;
  • DevOps labs;
  • disposable test environments;
  • security labs;
  • internal tooling;
  • self-hosted applications;
  • CI-style integration test machines;
  • learning Linux networking, storage, and cloud-init.

Avoid treating it as only a Docker replacement. Incus manages whole systems. A container usually behaves like a small Linux server with init, packages, services, users, networking, and persistent disks.

Main concepts

Concept What it means
Instance A container or VM managed by Incus.
Container Lightweight system container sharing the host kernel.
VM Full virtual machine with its own kernel.
Image Template used to create an instance.
Profile Reusable default config, devices, limits, and network/storage settings.
Storage pool Where instance disks, custom volumes, and snapshots live.
Network Managed bridges, physical NICs, OVN networks, or other network devices.
Project Namespace for separating instances, profiles, images, networks, and limits.
Remote Another Incus server or image server.
Snapshot Point-in-time instance state for rollback or backup.

Container or VM?

Choose a container when you want speed and low overhead:

incus launch images:debian/13 my-container

Choose a VM when you need stronger isolation or a real kernel boundary:

incus launch images:debian/13 my-vm --vm

Simple rule:

  • use containers for lightweight Linux services, labs, and test boxes;
  • use VMs for identity providers, security tooling, secrets managers, Windows, kernel work, or anything that should feel closer to a real server.

Daily admin cheat sheet

Inspect the host

incus version
incus info
incus storage list
incus network list
incus profile list
incus project list

Work with instances

incus list
incus launch images:ubuntu/24.04 web-01
incus launch images:debian/13 db-01 --vm
incus start web-01
incus stop web-01
incus restart web-01
incus delete web-01
incus delete web-01 --force

Enter and manage an instance

incus shell web-01
incus exec web-01 -- bash
incus exec web-01 -- systemctl status nginx
incus file push ./app.conf web-01/etc/app.conf
incus file pull web-01/etc/app.conf ./app.conf

View and change configuration

incus config show web-01
incus config edit web-01
incus config set web-01 limits.cpu 2
incus config set web-01 limits.memory 2GiB
incus config unset web-01 limits.memory

Devices and disks

incus config device list web-01
incus config device show web-01
incus config device add web-01 data disk source=/srv/web-data path=/data
incus config device remove web-01 data

Snapshots and rollback

incus snapshot web-01 before-upgrade
incus info web-01
incus restore web-01 before-upgrade
incus delete web-01/before-upgrade

Copy, move, and export

incus copy web-01 web-02
incus move web-02 web-renamed
incus export web-01 web-01.tar.gz
incus import web-01.tar.gz

Images

incus image list images: debian
incus image info images:debian/13
incus publish web-01 --alias web-template
incus image list local:
incus image delete web-template

Profiles

incus profile show default
incus profile create lab-small
incus profile edit lab-small
incus launch images:debian/13 test-01 --profile default --profile lab-small

Projects

incus project list
incus project create dev
incus project switch dev
incus project switch default

Remotes

incus remote list
incus remote add lab https://incus.example.com:8443
incus list lab:
incus copy web-01 lab:web-01

A concise Incus tutorial path

The nicest way to learn Incus is not one giant page. Use a short sequence where each page teaches one admin skill and ends with a working command set.

Recommended section structure:

  1. Incus overview - what Incus is, when to use containers vs VMs, and official links. This page.
  2. Install and initialize Incus - install packages, run incus admin init, create a storage pool, create a bridge, and verify the host.
  3. Everyday instance admin - launch, list, start, stop, restart, delete, shell, exec, files, limits, and logs.
  4. Images and templates - use remote images, publish a golden image, copy images, and clean old images.
  5. Storage - pools, volumes, disk devices, resizing, snapshots, export/import, and backup habits.
  6. Networking - managed bridges, static IPs, proxy devices, DNS names, port forwarding, and common troubleshooting.
  7. Profiles and projects - reusable configuration and clean separation between labs, prod-like workloads, and experiments.
  8. VMs with cloud-init - launch VMs, pass user-data, wait for boot, use the VM agent, and create repeatable service templates.
  9. Backups, migration, and remotes - export/import, copy between hosts, move workloads, and restore safely.
  10. Troubleshooting cookbook - agent not ready, image download failures, IP conflicts, storage full, broken profiles, stuck instances.

Each tutorial page should follow the same pattern:

Goal -> prerequisites -> commands -> verify -> cleanup -> common mistakes

Keep examples small and real. Prefer one clean Debian or Ubuntu instance per guide, then add notes for advanced cases.

Full Incus guide

Continue with these focused administrator guides:

  • Name instances clearly: service-role-number, for example web-01 or auth-vm-01.
  • Snapshot before risky changes.
  • Keep profiles boring and reusable.
  • Use projects to separate experiments from important workloads.
  • Prefer VMs for sensitive infrastructure.
  • Check incus list, incus info, and logs before guessing.
  • Document static IPs, ports, profiles, and storage pools near the service using them.
  • Clean up old snapshots, unused images, and dead test instances.

Quick safe practice lab

Create a temporary container, enter it, inspect it, snapshot it, and remove it:

incus launch images:debian/13 incus-lab-01
incus list incus-lab-01
incus shell incus-lab-01
incus snapshot incus-lab-01 clean-install
incus info incus-lab-01
incus delete incus-lab-01 --force

That small loop covers the core daily workflow: create, inspect, enter, snapshot, and delete.