Incus command cookbook

This is a practical map of the Incus CLI. Commands and syntax are based on the official Incus command reference and official how-to guides. Use the focused pages in this section for complete workflows.

Replace example names, addresses, storage pools, and remotes before running commands. Commands marked cluster, OVN, or destructive need the stated infrastructure and should not be run blindly on a production host. Incus adds commands over time, so confirm that your installed version supports a command with incus <command> --help; for example, incus port-forward is available in the current upstream documentation but might not exist in older distribution packages.

Discover the CLI

incus version
incus --help
incus --all --help
incus network --help
incus storage volume --help
incus launch --help

Use --project to operate in a project without switching the client default:

incus list --project dev
incus launch images:debian/13 dev-web-01 --project dev

Server and client basics

incus info
incus info --resources
incus version
incus remote list
incus project list
incus profile list

Configure a new server with the guided initializer:

sudo incus admin init
incus admin waitready

Show and change server settings. The server configuration reference documents valid keys and their scope.

incus config show
incus config get core.https_address
incus config set core.https_address=:8443
incus config unset core.https_address

Exposing the API on the network requires a firewall and explicit client authentication. Generate a one-time trust token on the server, then add the remote from the client:

incus config trust add workstation-01
incus remote add lab <trust-token>

Official references: server configuration and network exposure.

Instances

List, filter, and inspect instances:

incus list
incus list status=running
incus list type=container
incus list 'web-.*'
incus info web-01
incus info web-01 --show-log

Create a container or VM. launch creates and starts an instance; init creates it stopped.

incus launch images:debian/13 web-01
incus init images:debian/13 web-staging
incus start web-staging
incus launch images:debian/13 db-01 --vm
incus launch images:debian/13 limited-01 -c limits.cpu=1 -c limits.memory=192MiB
incus launch images:debian/13 vm-big-01 --vm -d root,size=30GiB

Pass a reviewed YAML instance configuration instead of a long list of flags:

incus config show web-01 --expanded
incus launch images:debian/13 web-from-yaml < config.yaml

Manage lifecycle state and wait for an expected state:

incus start web-01
incus stop web-01 --timeout 60
incus restart web-01
incus pause web-01
incus resume web-01
incus wait web-01 --state RUNNING

Delete is permanent and also deletes instance snapshots. Prefer the interactive alias below for day-to-day use.

incus delete web-01
incus delete disposable-01 --force

Protect a long-lived instance from accidental deletion:

incus config set db-01 security.protection.delete=true
incus config unset db-01 security.protection.delete

Rebuild replaces the root disk but preserves the instance configuration. Stop the instance and remove snapshots first.

incus stop web-01
incus rebuild images:debian/13 web-01
incus rebuild web-01 --empty

Official references: create instances and manage instances.

Access and troubleshoot instances

incus shell web-01
incus exec web-01 -- uname -a
incus exec web-01 -- systemctl status nginx
incus file push ./nginx.conf web-01/etc/nginx/nginx.conf
incus file pull web-01/var/log/nginx/access.log ./access.log
incus file push -r ./site web-01/var/www/site

The console is available before the VM agent. Use it when exec or file access is unavailable:

incus console db-01
incus console db-01 --show-log
incus start db-01 --console
incus console db-01 --type vga

Temporarily forward a local port to an instance. This listener stops when the command exits; it is not a persistent network forward.

incus port-forward web-01 80 8080
incus port-forward web-01 10.10.10.50:443 0.0.0.0:8443

Instance configuration and devices

incus config show web-01
incus config show web-01 --expanded
incus config get web-01 limits.memory
incus config set web-01 limits.cpu=2 limits.memory=2GiB
incus config unset web-01 limits.memory
incus config set web-01 user.role=web

Manage instance devices:

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 add web-01 http proxy listen=tcp:127.0.0.1:8080 connect=tcp:127.0.0.1:80
incus config device remove web-01 http
incus config device remove web-01 data

Hardware devices affect host isolation. Inspect the host and use a VM when that is the safer boundary:

incus config device add gpu-vm gpu0 gpu
incus config device add test-01 usb0 usb vendorid=1234 productid=5678

Snapshots, backups, copies, and moves

incus snapshot create web-01 before-upgrade
incus snapshot create web-01 nightly --reuse
incus info web-01
incus snapshot restore web-01 before-upgrade
incus snapshot delete web-01 before-upgrade

Schedule snapshots with expiry so storage does not grow without bound:

incus config set web-01 snapshots.schedule=@daily
incus config set web-01 snapshots.expiry=7d
incus config set web-01 snapshots.pattern=snap%d

Export and test an import. Custom storage volumes are independent resources and must be backed up separately.

incus export web-01 /backups/web-01.tar.gz --instance-only
incus import /backups/web-01.tar.gz restored-web-01
incus copy web-01 backup-host:web-01
incus move web-01 new-host:web-01

Images

incus image list images: debian
incus image info images:debian/13
incus image list local:
incus publish web-01 --alias debian-web-base
incus image copy debian-web-base backup-host: --alias debian-web-base
incus image export debian-web-base debian-web-base
incus image import debian-web-base.tar.gz --alias debian-web-base-restored
incus image delete debian-web-base

Use a cloud image when cloud-init is required:

incus launch images:debian/trixie/cloud cloud-vm-01 --vm

Networks

Inspect and manage a bridge network:

incus network list
incus network show incusbr0
incus network info incusbr0
incus network create labbr0 --type=bridge ipv4.address=10.50.0.1/24 ipv4.nat=true
incus network attach labbr0 web-01 eth1 eth1
incus network detach labbr0 web-01 eth1
incus network delete labbr0

Set a static DHCP lease on an Incus-managed bridge by overriding the NIC inherited from a profile:

incus config device override web-01 eth0 ipv4.address=10.10.10.50
incus restart web-01

Network forwards are persistent at the managed bridge or OVN network level. Choose a non-conflicting listen address and use an address in the network subnet as the target.

incus network forward create incusbr0 192.0.2.10 target_address=10.10.10.50
incus network forward port add incusbr0 192.0.2.10 tcp 443 10.10.10.50 8443
incus network forward delete incusbr0 192.0.2.10

ACLs control traffic for supported bridge and OVN configurations:

incus network acl create web-ingress
incus network acl rule add web-ingress ingress action=allow protocol=tcp destination_port=443
incus config device set web-01 eth0 security.acls=web-ingress
incus network acl show-log web-ingress

Official references: networks, forwards, and ACLs.

Storage, volumes, and buckets

incus storage list
incus storage show default
incus storage info default
incus storage volume list default
incus storage volume create default app-data
incus storage volume attach default app-data web-01 app-data /srv/app-data
incus storage volume set default app-data size=10GiB
incus storage volume snapshot default app-data before-change
incus storage volume restore default app-data before-change
incus storage volume detach default app-data web-01
incus storage volume delete default app-data

Storage buckets expose S3-compatible object storage only on a storage driver that supports buckets. Configure the S3 address before using locally hosted buckets.

incus config set core.storage_buckets_address=:8555
incus storage bucket create default app-backups
incus storage bucket set default app-backups size=10GiB
incus storage bucket key create default app-backups ci-writer --role=admin
incus storage bucket key list default app-backups
incus storage bucket delete default app-backups

Official references: volumes and buckets.

Profiles and projects

incus profile list
incus profile create small
incus profile set small limits.cpu=2 limits.memory=2GiB
incus profile add web-01 small
incus profile remove web-01 small
incus profile delete small

incus project list
incus project create dev
incus project set dev limits.instances=20
incus project switch dev
incus launch images:debian/13 dev-test
incus project switch default

Remotes, aliases, and client defaults

incus remote list
incus remote add lab 192.0.2.10
incus remote get-default
incus remote switch lab
incus remote set-keepalive lab 30
incus remote set-keepalive lab 0
incus remote remove lab

Aliases belong to the local client. An alias named delete intentionally adds an interactive confirmation to that command.

incus alias list
incus alias add delete "delete --interactive"
incus alias add cat "exec @ARG1@ -- cat @ARG2@"
incus cat web-01 /etc/os-release
incus alias remove cat

Inspect client defaults before setting them. Their available keys depend on the installed client version.

incus default show
incus default set --help
incus default unset --help

Monitoring, operations, and warnings

incus top
incus monitor --type=lifecycle
incus monitor --pretty --type=logging --loglevel=info
incus operation list
incus operation show <operation-uuid>
incus operation delete <operation-uuid>
incus warning list
incus warning show <warning-uuid>
incus warning acknowledge <warning-uuid>

incus operation delete attempts to cancel the matching background operation. Investigate the operation before cancelling it.

Clusters

Use these only on an initialized cluster. Cluster storage and network creation requires member-specific configuration; follow the official cluster guides before changing production membership.

incus cluster list
incus cluster show server1
incus cluster group create gpu
incus cluster group assign server1 default,gpu
incus launch images:debian/13 gpu-test --target=@gpu
incus list --all-projects

API, Web UI, and low-level administration

The CLI can send raw API queries. Use the REST API documentation to verify request bodies before mutating resources.

incus query /1.0
incus query /1.0/instances?recursion=2
incus webui
incus manpage --help
incus low-level --help
incus admin recover --help

Avoid incus admin sql, incus admin shutdown, and low-level database commands unless following a tested recovery procedure from the official documentation.

Command-family coverage

Command family	Primary guide
`admin`, `config`, `version`, `webui`	This page and installation
`alias`, `default`, `remote`	This page and remotes
`launch`, `init`, `list`, `info`, lifecycle, `rebuild`, `wait`	Everyday administration
`exec`, `shell`, `console`, `file`, `port-forward`	This page and troubleshooting
`copy`, `move`, `export`, `import`, `snapshot`, `publish`	Backups and migration
`image`	Images and templates
`network`	Networking
`storage`	Storage
`profile`, `project`	Profiles and projects
`cluster`	Advanced usage
`monitor`, `operation`, `top`, `warning`	This page and troubleshooting
`query`, `low-level`, `manpage`	This page and the official CLI reference