Managing containers and VMs with Incus

Once Incus is installed, day-to-day work is about instances. This guide covers the image registry (searching, filtering, pinning a version), launching containers and virtual machines, project management, access through exec and shell, configuration (limits, devices, profiles), file transfer and the console. The commands apply to Incus 7.0.

What you will learn

Find and filter images in the registry.
Launch containers and virtual machines, and set their resources.
Organise with projects, run commands through exec and shell.
Configure instances and profiles, handle files and the console.

The Incus image registry

Incus uses a system of remotes to reach images hosted elsewhere. The default remote is called images and it downloads official images from a central server, reachable through the images: prefix.

To list the images available on the images: remote:

incus image list images:

The image server at images.linuxcontainers.org offers a wide variety of Linux distributions: Ubuntu, Debian, CentOS and many others. Each image is classified by version and architecture (amd64, arm64) and comes in container and virtual machine flavours. Those images are continuously refreshed, which keeps environments stable and patched.

Filtering images

To list the images available for a specific version and architecture, such as Debian 13 on arm64:

incus image list images: debian/13 arm64

The -c option customises the displayed columns. The available ones are:

l: short alias
f: fingerprint
d: description
a: architecture
s: size
u: upload date
t: type (container or virtual machine)

For instance, to show only the alias, architecture, type and size:

incus image list images: -c lats debian/13
+----------------------------------+--------------+-----------------+-----------+
|              ALIAS               | ARCHITECTURE |      TYPE       |   SIZE    |
+----------------------------------+--------------+-----------------+-----------+
| debian/13 (7 more)               | x86_64       | CONTAINER       | 100.42MiB |
+----------------------------------+--------------+-----------------+-----------+
| debian/13 (7 more)               | x86_64       | VIRTUAL-MACHINE | 346.74MiB |
+----------------------------------+--------------+-----------------+-----------+
| debian/13/cloud (3 more)         | x86_64       | CONTAINER       | 132.21MiB |
+----------------------------------+--------------+-----------------+-----------+

What about idempotence?

How do you guarantee idempotence when Incus images carry no tags, as Docker ones do? Without tags it is hard to be sure every instance uses the exact same image version. One solution is to rely on unique image fingerprints and to create aliases that carry the date:

incus image copy images:debian/13 local: --alias debian-lts-$(date +%Y%m%d)

That guarantees you always work from the same image version. To store those images centrally and reliably, configure a private remote or your own image server, with regular backups. Automating image builds covers that reproducible construction with Packer and Ansible.

Launching an instance

To launch an instance from an image, use incus launch:

incus launch images:debian/13 my-container

That creates and starts a container named my-container based on a Debian 13 image. It runs in the background and you interact with it through Incus. For a virtual machine, the same command takes --vm:

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

To check what type an instance is:

incus info my-vm
Name: my-vm
Status: RUNNING
Type: virtual-machine
Architecture: x86_64
PID: 16167
Created: 2026/07/01 07:45 UTC

Operating System:
  OS: Debian GNU/Linux
  OS Version: 13
  Kernel Version: 6.12.94+deb13-amd64
  Hostname: my-vm

Resources:
  Processes: 106

The Type: virtual-machine line says the instance is a VM, not a container. Looking further into the properties, you also find QEMU, the hypervisor running it.

Setting resources for an instance

For a virtual machine with a 30 GiB disk:

incus launch images:debian/13 debian-vm-big --vm --device root,size=30GiB

To limit a container to one vCPU and 192 MiB of RAM:

incus launch images:debian/13 debian-limited --config limits.cpu=1 --config limits.memory=192MiB

Listing instances

To show the running instances:

incus list

+---------------+---------+-----------------------+------+-----------------+-----------+
|     NAME      |  STATE  |         IPV4          | IPV6 |      TYPE       | SNAPSHOTS |
+---------------+---------+-----------------------+------+-----------------+-----------+
| my-vm         | RUNNING | 10.107.24.37 (enp5s0) |      | VIRTUAL-MACHINE | 0         |
+---------------+---------+-----------------------+------+-----------------+-----------+
| my-container  | RUNNING | 10.107.24.95 (eth0)   |      | CONTAINER       | 0         |
+---------------+---------+-----------------------+------+-----------------+-----------+

Project management

A project in Incus compartmentalises a set of resources (containers, virtual machines, volumes, networks) in an independent space, handy for separating test, development and production. The global view, across every project, comes with --all-projects:

incus list --all-projects

To create a project, switch between projects and compartmentalise resources finely, see profiles and projects, which covers creation, switching and isolation strategies.

Lifecycle: start, stop and delete

Instances are managed with simple commands.

incus start my-instance    # start
incus stop my-instance     # stop
incus restart my-instance  # restart
incus delete my-instance   # delete a stopped instance, and all its data

A deleted instance cannot be recovered. Combining stop and a global listing shows the resulting state:

incus stop --project default my-vm
incus list --all-projects

+---------+---------------+---------+------+------+-----------------+-----------+
| PROJECT |     NAME      |  STATE  | IPV4 | IPV6 |      TYPE       | SNAPSHOTS |
+---------+---------------+---------+------+------+-----------------+-----------+
| default | my-vm         | STOPPED |      |      | VIRTUAL-MACHINE | 0         |
+---------+---------------+---------+------+------+-----------------+-----------+
| default | my-container  | RUNNING |      |      | CONTAINER       | 0         |
+---------+---------------+---------+------+------+-----------------+-----------+

Interacting: exec and shell access

Incus reaches instances without configuring any network access on them. To expose a service or drive instance addressing, see Incus networking.

Running a command in an instance

incus exec my-instance -- <command>

For example, to refresh the package list in a container:

incus exec my-container -- apt update

Reaching the instance shell

To interact directly through a shell, use bash or sh depending on the instance operating system:

incus shell my-vm

You then take full control of the instance, as if connected to its terminal.

Configuring instances

You configure instances by changing properties, options or by adding devices.

Use incus config set to set options such as memory or CPU limits:

incus config set my-vm limits.memory=1GiB

To add a device, such as a disk:

incus config device add my-vm disk-storage-device disk source=/home/user/data path=/opt

Devices also cover storage volumes and graphics cards. To attach a persistent volume, see Incus storage; to expose a graphics card to an instance, see GPU passthrough.

Using profiles

A profile centralises a reusable configuration (resource limits, devices, options) applied to one or more instances. List the existing ones with:

incus profile list

Then attach one or more profiles at launch with --profile:

incus launch images:debian/13 my-instance --profile default --profile my-profile

To create a profile, add settings to it, combine several and understand their precedence, see profiles and projects.

Configuring instances with cloud-init

Containers and virtual machines can be configured at boot with cloud-init, which automates tasks such as installing packages, configuring networks or creating users. The cloud image variants (debian/13/cloud) carry the agent that reads that configuration.

Managing instance files

You manage instance files with the Incus client, without reaching the instance over the network. Files can be edited or deleted individually, pushed from or pulled to the local machine. For containers those operations always work, handled directly by Incus. For virtual machines, the incus-agent process has to be running inside for them to work.

Editing instance files

incus file edit <instance>/<path>

For example:

incus file edit my-container/etc/hosts

The file has to exist already on the instance: edit cannot create one.

Deleting instance files

incus file delete <instance>/<path>

Pulling files to the local machine

incus file pull <instance>/<path> <local path>

For instance, to pull /etc/hosts into the current directory:

incus file pull my-instance/etc/hosts .

You can also pull a file to standard output and pipe it into another program, for example to read a log:

incus file pull my-instance/var/log/syslog - | less

To pull a whole directory, add -r:

incus file pull -r <instance>/<directory> <local path>

Pushing files to the instance

incus file push <local path> <instance>/<path>
incus file push -r <local path> <instance>/<directory>

Reaching the instance console

The incus console command connects to the console of an instance. It is available from the moment the instance starts, which lets you read boot messages and debug startup problems, for a container or a virtual machine.

An interactive console

incus console <instance>

Showing boot logs

incus console <instance> --show-log

Starting an instance with the console attached

incus start <instance> --console

The graphical console (virtual machines)

For virtual machines you can connect to the graphical console, which lets you install an operating system through a graphical interface or run a desktop environment. The added benefit is that the console is available even before the incus-agent process runs.

To start the VGA console with graphical output you need a SPICE client. Incus supports two:

remote-viewer (often in the virt-viewer package)
spicy (in the spice-client-gtk or spice-gtk-tools package)

Then:

incus console <vm> --type vga

Key points

The image registry is queried with incus image list images:, filterable by distribution and architecture.
incus launch creates and starts an instance; the --vm option makes it a virtual machine.
Projects compartmentalise resources; --all-projects gives the global view.
incus exec and incus shell reach an instance with no network; incus file transfers files.
Profiles centralise a reusable configuration applied across several instances.

FAQ: common questions about Incus instances

How do you launch a container or a VM with Incus?

You use incus launch with an image from the images: remote. For example incus launch images:debian/13 my-container creates a container, and the --vm option makes it a virtual machine. The instance starts in the background.

The incus launch command

incus launch creates and starts an instance from an image on the images: remote:

incus launch images:debian/13 my-container

For a virtual machine, add the --vm option:

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

You set resources at launch time with --config limits.cpu=1 --config limits.memory=192MiB or --device root,size=30GiB.

How do you list the running Incus instances?

The incus list command shows the instances of the current project with their state, address and type. The --all-projects option gives the global view across every project, which helps when an instance was created in another project.

incus list

The incus list command shows the instances of the current project, with their state, their IPv4 and their type:

incus list

To see everything across all projects, use --all-projects:

incus list --all-projects

That is the reflex when an instance seems missing: it may well live in another project.

How do you run a command or get inside an Incus instance?

You run a one-off command with incus exec my-instance -- command, with no network access to configure. For an interactive session, incus shell my-vm opens a shell in the instance, as if you were connected to its terminal.

exec for a command, shell for a session

The incus exec command runs a one-off command in an instance, with no network access to set up:

incus exec my-container -- apt update

For an interactive session, incus shell opens a shell in the instance:

incus shell my-vm

You then take control of the instance as if from its local terminal.

How do you transfer a file to or from an Incus instance?

You use incus file push to send a local file to the instance, and incus file pull to fetch one. The -r option transfers a whole directory. For a virtual machine, the incus-agent process has to be running inside the instance.

incus file push and pull

The Incus client transfers files with no network access to the instance:

incus file push file.conf my-instance/etc/file.conf
incus file pull my-instance/etc/hosts .

The -r option transfers a whole directory. You can also edit an existing file with incus file edit.

For a virtual machine, the incus-agent process has to be running inside it for these operations to work.

Next steps

Incus storage: the pools and volumes that actually carry the data of the instances you manipulate.
Profiles and projects: stop configuring instance by instance and factor out what repeats.
Terraform provider: describe your instances as code instead of replaying the same commands.