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: upcoming
Feature releases: Incus 0.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#
The easiest way to install Incus on Linux is to install the Debian and Ubuntu package from Zabbly, which is available for both Debian and Ubuntu.
You can also find native builds of the Incus client on GitHub:
Incus client for Linux:
bin.linux.incus.aarch64
,bin.linux.incus.x86_64
Incus client for Windows:
bin.windows.incus.aarch64.exe
,bin.windows.incus.x86_64.exe
Incus client for macOS:
bin.macos.incus.aarch64
,bin.macos.incus.x86_64
Debian and Ubuntu package from Zabbly#
Currently the easiest way to install Incus is to use the Debian or Ubuntu packages provided by Zabbly. There are two repositories available, one for the current stable release and one for daily (untested) builds.
Installation instructions may be found here: https://github.com/zabbly/incus
If you prefer a different installation method, see How to install Incus.
Allow your user to control Incus
Access to Incus in the packages above is controlled through two groups:
incus
allows basic user access, no configuration and all actions restricted to a per-user project.incus-admin
allows full control over Incus.
To control Incus without having to run all commands as root, you can add yourself to the
incus-admin
group:sudo adduser YOUR-USERNAME incus-admin newgrp incus-admin
The
newgrp
step is needed in any terminal that interacts with Incus until you restart your user session.Initialize Incus with:
incus admin init --minimal
This will create a minimal setup with default options. If you want to tune the initialization options, see How to initialize Incus for more information.
Other operating systems#
Important
The builds for other operating systems include only the client, not the server.
Incus publishes builds of the Incus client for macOS through Homebrew.
To install the feature branch of Incus, run:
brew install incus
The Incus client on Windows is provided as a Chocolatey package. To install it:
Install Chocolatey by following the installation instructions.
Install the Incus client:
choco install incus
You can also find native builds of the Incus client on GitHub. To download a specific build:
Make sure that you are logged into your GitHub account.
Filter for the branch or tag that you are interested in (for example, the latest release tag or
main
).Select the latest build and download the suitable artifact.
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
(>= 4.0.0 required)
available for Incus development. Additionally, Incus requires a modern Golang (see Go)
version to work. On Ubuntu, you can get those with:
sudo apt update
sudo apt install acl attr autoconf automake dnsmasq-base git libacl1-dev libcap-dev liblxc1 liblxc-dev libsqlite3-dev libtool libudev-dev liblz4-dev libuv1-dev make pkg-config rsync squashfs-tools tar tcl xz-utils ebtables
command -v snap >/dev/null || sudo apt-get install snapd
sudo snap install --classic go
Note
If you use the liblxc-dev
package and get compile time errors when building the go-lxc
module,
ensure that the value for INC_DEVEL
is 0
for your liblxc
build. To check that, look at /usr/include/lxc/version.h
.
If the INC_DEVEL
value is 1
, replace it with 0
to work around the problem. It’s a packaging bug, and
we are aware of it for Ubuntu 22.04/22.10. Ubuntu 23.04/23.10 does not have this problem.
There are a few storage drivers for Incus besides the default dir
driver.
Installing these tools adds a bit to initramfs and may slow down your
host boot, but are needed if you’d like to use a particular driver:
sudo apt install lvm2 thin-provisioning-tools
sudo apt install btrfs-progs
To run the test suite, you’ll also need:
sudo apt install busybox-static curl gettext jq sqlite3 socat bind9-dnsutils
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-0.1.tar.gz
cd incus-0.1
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.
user@host:~$
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)"
user@host:~$
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 a 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.