How to install Incus

The easiest way to install Incus is to install one of the available packages, but you can also install Incus from the sources.

After installing Incus, make sure you have an incus-admin group on your system. Users in this group can interact with Incus. See Manage access to Incus for instructions.

Choose your release

Incus maintains different release branches in parallel:

  • Long term support (LTS) releases: 6.0

  • Feature releases: Incus 6.x

LTS releases are recommended for production environments, because they benefit from regular bugfix and security updates. However, there are no new features added to an LTS release, nor any kind of behavioral change.

To get all the latest features and monthly updates to Incus, use the feature release branch instead.

Install Incus from a package

The Incus daemon only works on Linux. The client tool (incus) is available on most platforms.

Linux

Packages are available for a number of Linux distributions, either in their main repository or through third party repositories.

Incus and all of its dependencies are available in Alpine Linux’s edge main and community repository as incus.

Uncomment the edge main and community repositories in /etc/apk/repositories and run:

apk update

Install Incus with:

apk add incus incus-client

If running virtual machines, also do:

apk add incus-vm

Then enable and start the service:

rc-update add incusd
rc-service incusd start

Please report packaging issues here.

Other operating systems

Important

The builds for other operating systems include only the client, not the server.

Homebrew

Incus publishes builds of the Incus client for macOS through Homebrew.

To install the feature branch of Incus, run:

brew install incus

Colima

Incus is supported as a runtime on Colima.

Install Colima with:

brew install colima

Start Colima with Incus as runtime with:

colima start --runtime incus

For any Colima related issues, please file an issue in the project repository.

You can also find native builds of the Incus client on GitHub:

Install Incus from source

Follow these instructions if you want to build and install Incus from the source code.

We recommend having the latest versions of liblxc (>= 5.0.0 required) available for Incus development. Additionally, Incus requires a modern Golang (see Go) version to work.

You can get the development resources required to build Incus on your Alpine Linux via the following command:

apk add acl-dev autoconf automake eudev-dev gettext-dev go intltool libcap-dev libtool libuv-dev linux-headers lz4-dev tcl-dev sqlite-dev lxc-dev make xz

To take advantage of all the necessary features of Incus, you must install additional packages. You can reference the list of packages you need to use specific functions from LXD package definition in Alpine Linux repository. Also you can find the package you need with the binary name from Alpine Linux packages contents filter.

Install the main dependencies:

apk add acl attr ca-certificates cgmanager dbus dnsmasq lxc libintl iproute2 iptables netcat-openbsd rsync squashfs-tools shadow-uidmap tar xz

Install the extra dependencies for running virtual machines:

apk add qemu-system-x86_64 qemu-chardev-spice qemu-hw-usb-redirect qemu-hw-display-virtio-vga qemu-img qemu-ui-spice-core ovmf sgdisk util-linux-misc virtiofsd

After preparing the source from a release tarball or git repository, you need follow the below steps to avoid known issues during build time:

NOTE: Some build errors may occur if /usr/local/include doesn’t exist on the system. Also, due to a gettext issue, you may need to set those additional environment variables:

export CGO_LDFLAGS="$CGO_LDFLAGS -L/usr/lib -lintl"
export CGO_CPPFLAGS="-I/usr/include"

Note

On ARM64 CPUs you need to install AAVMF instead of OVMF for UEFI to work with virtual machines. In some distributions this is done through a separate package.

From source: Build the latest version

These instructions for building from source are suitable for individual developers who want to build the latest version of Incus, or build a specific release of Incus which may not be offered by their Linux distribution. Source builds for integration into Linux distributions are not covered here and may be covered in detail in a separate document in the future.

git clone https://github.com/lxc/incus
cd incus

This will download the current development tree of Incus and place you in the source tree. Then proceed to the instructions below to actually build and install Incus.

From source: Build a release

The Incus release tarballs bundle a complete dependency tree as well as a local copy of libraft and libcowsql for Incus’ database setup.

tar zxvf incus-6.0.0.tar.gz
cd incus-6.0.0

This will unpack the release tarball and place you inside of the source tree. Then proceed to the instructions below to actually build and install Incus.

Start the build

The actual building is done by two separate invocations of the Makefile: make deps – which builds libraries required by Incus – and make, which builds Incus itself. At the end of make deps, a message will be displayed which will specify environment variables that should be set prior to invoking make. As new versions of Incus are released, these environment variable settings may change, so be sure to use the ones displayed at the end of the make deps process, as the ones below (shown for example purposes) may not exactly match what your version of Incus requires:

We recommend having at least 2GiB of RAM to allow the build to complete.

~$ make deps
...make[1]: Leaving directory '/root/go/deps/cowsql'# environment Please set the following in your environment (possibly ~/.bashrc)#  export CGO_CFLAGS="${CGO_CFLAGS} -I$(go env GOPATH)/deps/cowsql/include/ -I$(go env GOPATH)/deps/raft/include/"#  export CGO_LDFLAGS="${CGO_LDFLAGS} -L$(go env GOPATH)/deps/cowsql/.libs/ -L$(go env GOPATH)/deps/raft/.libs/"#  export LD_LIBRARY_PATH="$(go env GOPATH)/deps/cowsql/.libs/:$(go env GOPATH)/deps/raft/.libs/:${LD_LIBRARY_PATH}"#  export CGO_LDFLAGS_ALLOW="(-Wl,-wrap,pthread_create)|(-Wl,-z,now)"
~$ make

From source: Install

Once the build completes, you simply keep the source tree, add the directory referenced by $(go env GOPATH)/bin to your shell path, and set the LD_LIBRARY_PATH variable printed by make deps to your environment. This might look something like this for a ~/.bashrc file:

export PATH="${PATH}:$(go env GOPATH)/bin"
export LD_LIBRARY_PATH="$(go env GOPATH)/deps/cowsql/.libs/:$(go env GOPATH)/deps/raft/.libs/:${LD_LIBRARY_PATH}"

Now, the incusd and incus binaries will be available to you and can be used to set up Incus. The binaries will automatically find and use the dependencies built in $(go env GOPATH)/deps thanks to the LD_LIBRARY_PATH environment variable.

Machine setup

You’ll need sub{u,g}ids for root, so that Incus can create the unprivileged containers:

echo "root:1000000:1000000000" | sudo tee -a /etc/subuid /etc/subgid

Now you can run the daemon (the --group sudo bit allows everyone in the sudo group to talk to Incus; you can create your own group if you want):

sudo -E PATH=${PATH} LD_LIBRARY_PATH=${LD_LIBRARY_PATH} $(go env GOPATH)/bin/incusd --group sudo

Note

If newuidmap/newgidmap tools are present on your system and /etc/subuid, etc/subgid exist, they must be configured to allow the root user a contiguous range of at least 10M UID/GID.

Manage access to Incus

Access control for Incus is based on group membership. The root user and all members of the incus-admin group can interact with the local daemon. See Access to the Incus daemon for more information.

If the incus-admin group is missing on your system, create it and restart the Incus daemon. You can then add trusted users to the group. Anyone added to this group will have full control over Incus.

Because group membership is normally only applied at login, you might need to either re-open your user session or use the newgrp incus-admin command in the shell you’re using to talk to Incus.

Important

Local access to Incus through the Unix socket always grants full access to Incus. This includes the ability to attach file system paths or devices to any instance as well as tweak the security features on any instance.

Therefore, you should only give such access to users who you’d trust with root access to your system.

Upgrade Incus

After upgrading Incus to a newer version, Incus might need to update its database to a new schema. This update happens automatically when the daemon starts up after an Incus upgrade. A backup of the database before the update is stored in the same location as the active database (at /var/lib/incus/database).

Important

After a schema update, older versions of Incus might regard the database as invalid. That means that downgrading Incus might render your Incus installation unusable.

In that case, if you need to downgrade, restore the database backup before starting the downgrade.