How To Install Incus on Debian 13

Incus represents the next generation of Linux container and virtual machine management, offering a powerful, open-source platform for modern infrastructure deployments. As a community-maintained fork of LXD, Incus provides system administrators with unprecedented flexibility in managing containerized workloads and virtualized environments. Debian 13 (Trixie), the latest stable distribution from the Debian project, serves as an ideal host operating system for Incus due to its robust package ecosystem and long-term stability. This comprehensive guide walks through the complete process of installing Incus on Debian 13, covering everything from system prerequisites to advanced configuration options. Whether you’re a seasoned Linux professional or just beginning your containerization journey, this article provides actionable steps to get Incus running efficiently on your Debian 13 system.

What is Incus? Understanding the Container Management Platform

Incus functions as a sophisticated system container and virtual machine manager built specifically for Linux environments. It bridges the gap between lightweight containers and full virtual machines, allowing administrators to deploy both Linux containers and QEMU virtual machines from a single unified platform. The project emerged when the original LXD maintainers created a community-driven fork, resulting in Incus as a truly open-source solution with transparent governance and regular feature releases.

The platform excels at managing complex infrastructure scenarios. Users can spin up thousands of isolated Linux containers with minimal overhead, each running complete Linux distributions independently. Simultaneously, Incus supports full virtual machine deployments for workloads requiring complete hardware isolation. This flexibility makes Incus invaluable for data center operations, development environments, testing infrastructure, and educational institutions.

What sets Incus apart from traditional virtualization approaches is its container-first philosophy combined with optional VM support. Containers boot in milliseconds and consume fractions of the resources required by hypervisor-based solutions. Yet for applications demanding hardware isolation or running non-Linux operating systems, Incus VM support delivers that capability without switching platforms.

Key Differences Between Incus and LXD

Understanding the distinction between Incus and LXD proves essential for users familiar with LXD or evaluating container platforms. While Incus originated from LXD’s codebase, the projects have diverged significantly since the fork. LXD remains maintained by Canonical and integrated into Ubuntu’s ecosystem, while Incus has evolved as a community-driven project with its own release cycles and feature roadmap.

Performance characteristics diverge between the two platforms. Incus typically delivers faster container creation, improved resource management, and more granular control over system resources. The developer experience differs as well, with Incus offering streamlined command-line interfaces and more intuitive configuration procedures. API compatibility remains largely preserved, enabling relatively straightforward migrations from LXD to Incus for existing deployments.

Community support structures also differ. Incus benefits from a dedicated community forum and active development channel where contributors directly influence feature development. LXD maintains Canonical’s enterprise support model, which appeals to organizations requiring commercial backing. For open-source advocates prioritizing community involvement, Incus represents the natural choice.

System Requirements for Installing Incus on Debian 13

Before beginning the Incus installation process, verify your Debian 13 system meets all minimum requirements. Undersized systems may experience performance issues or fail container creation entirely. This section outlines the specifications necessary for successful Incus deployment.

Processor Architecture and CPU Requirements

Incus supports x86_64, ARM64, and POWER architectures, with x86_64 representing the most common deployment target. A modern processor with virtualization support (Intel VT-x or AMD-V) is strongly recommended for virtual machine workloads. Minimum processors include Intel Xeon E3 series, AMD Ryzen 5, or equivalent ARM processors for data center deployments. Personal development systems benefit from newer processors but can function with older hardware, though performance will be limited.

Memory and Storage Specifications

Minimum RAM for basic Incus operations starts at 2GB, though 4GB provides more practical headroom for testing environments. Production deployments should allocate at least 8GB to 16GB of RAM to comfortably run multiple containers and VMs simultaneously. Storage requirements depend entirely on your anticipated workload. Reserve a minimum of 5GB for the Incus installation and system files, plus additional capacity for container images, instance storage, and snapshots. Enterprise deployments frequently allocate 100GB to 500GB or more depending on instance density and retention policies.

Kernel and Cgroup Requirements

Debian 13 ships with Linux kernel 6.1 or later, fully meeting Incus requirements. However, verify your kernel version matches or exceeds 5.4 for basic container support. Incus on Debian 13 benefits from cgroup v2 support, a modern control group implementation that simplifies resource management. Modern kernels include this by default, but older systems may require manual configuration.

Network and Connectivity

A stable network connection is essential during installation for downloading packages and images. Systems requiring air-gapped deployments need alternative package source configurations. Network interface cards supporting bridge creation enable advanced networking features like custom network bridges and VLAN segmentation.

Pre-Installation Prerequisites and System Verification

Proper preparation before installation prevents common deployment issues and ensures Incus operates at peak efficiency.

Verifying Your Debian 13 Installation

Confirm your system is genuinely running Debian 13 by checking the /etc/os-release file:

cat /etc/os-release

The output should indicate “Debian GNU/Linux 13 (trixie)” or similar. If you see a different version number, upgrade your system first using apt full-upgrade and reboot before proceeding.

Checking Kernel Features and Virtualization Support

Modern container management requires specific kernel features. Verify support by examining the kernel configuration:

grep -i "^config_namespaces\|^config_cgroups\|^config_kvm" /boot/config-$(uname -r)

All entries should return “y” or “m”. For virtualization support, check whether your CPU supports KVM:

grep -o 'vmx\|svm' /proc/cpuinfo | uniq

A non-empty result indicates processor virtualization extensions are available. If no output appears, verify virtualization is enabled in BIOS settings. This typically appears under settings labeled “VT-x” (Intel) or “AMD-V” (AMD).

Verifying Available Disk Space

Check available storage on your root filesystem:

df -h /

Ensure at least 10GB of free space for testing environments or 50GB for production systems. If space is limited, allocate additional storage before continuing.

Updating Package Lists and Upgrading System Packages

Update your package cache and upgrade existing packages to their latest versions:

sudo apt update
sudo apt full-upgrade

This step ensures your system has current security patches and necessary dependencies for Incus installation.

Installation Methods for Debian 13

Three primary approaches exist for installing Incus on Debian 13, each suited to different requirements and preferences.

Native Debian Repository Installation represents the simplest approach, leveraging packages maintained by the Debian project. This method guarantees stability and long-term support but may provide slightly older Incus versions. The installation command is straightforward: sudo apt install incus.

Zabbly Repository Installation provides access to the latest stable Incus releases while maintaining compatibility with Debian 13. This community-maintained repository delivers new features and improvements faster than native packages. Installation involves adding a GPG key and creating a repository source file, then installing from the repository. Most production deployments favor this approach for balancing stability with feature access.

Building from Source appeals to developers requiring cutting-edge features or customized builds. This method demands compilation tools, Go language support, and development libraries. Source compilation takes longer and requires technical expertise but provides ultimate customization potential.

Method 1: Installing Incus from Debian 13 Native Repositories

The native Debian repository offers a rapid installation path suitable for testing and learning Incus fundamentals.

Step-by-Step Installation Procedure

First, ensure your package lists are current:

sudo apt update

Next, install Incus and its base components:

sudo apt install incus

The package manager automatically resolves dependencies and downloads required libraries. During installation, you may see prompts asking about package configurations. Select the default options unless you have specific requirements.

After installation completes, add your user to the Incus group to avoid requiring sudo for every command:

sudo usermod -a -G incus $USER

Then switch to the new group without logging out:

newgrp incus

Verify installation success by checking the Incus version:

incus --version

You should see output like “incus 0.4.0” or similar, indicating successful installation.

Starting the Incus Service

The Incus daemon (incusd) manages container and VM lifecycle. Start the service manually:

sudo systemctl start incus

Enable automatic startup at boot time:

sudo systemctl enable incus

Verify the daemon is running:

sudo systemctl status incus

Successful output shows “active (running)” with a green indicator. If the service fails to start, check logs for diagnostic information:

sudo journalctl -u incus -n 50

Method 2: Installing Incus via the Zabbly Repository (Recommended)

The Zabbly community repository provides up-to-date Incus packages with excellent stability.

Adding the Zabbly GPG Key

Zabbly signs packages with a GPG key for security verification. Download and store the key:

curl -fsSL https://zabbly.com/incus/incus.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/zabbly.gpg > /dev/null

This command downloads the key, converts it from ASCII armor format, and stores it in the system keyring. The GPG signature ensures packages haven’t been tampered with or modified maliciously.

Configuring the Zabbly Repository Source

Create a repository source file using the DEB822 format:

sudo bash -c 'cat > /etc/apt/sources.list.d/zabbly-incus.sources << EOF
Enabled: yes
Types: deb
URIs: https://zabbly.com/incus
Suites: debian-$(. /etc/os-release && echo $VERSION_CODENAME)
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/zabbly.gpg
EOF'

This configuration automatically detects your Debian version and system architecture. The Enabled: yes directive activates the repository immediately upon creation.

Installing Incus from Zabbly

Update your package cache to recognize the new repository:

sudo apt update

Install Incus along with recommended components:

sudo apt install incus incus-tools incus-doc

The package manager fetches the latest Incus version along with command-line tools and documentation. Installation typically completes within a few minutes depending on network speed.

Verifying Zabbly Installation

Confirm successful installation by checking the package source:

apt-cache policy incus

The output should display the Zabbly repository URL as the primary source. Version information confirms the installed package comes from Zabbly rather than the Debian repository.

Method 3: Building Incus from Source (Advanced)

Building Incus from source code appeals to developers requiring customization or working with uncommon architectures.

Installing Compilation Dependencies

Incus compilation requires several development tools and libraries. Install them all at once:

sudo apt install build-essential git golang-go libacl1-dev libcap-dev libseccomp-dev pkg-config

These packages provide the C compiler, Git version control, Go programming language, and kernel headers necessary for compilation.

Cloning the Incus Repository

Download the latest Incus source code:

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

Entering the directory positions you in the source tree for the next compilation steps.

Building Incus Binaries

The Makefile in the source directory orchestrates the build process:

make

Compilation takes 5-15 minutes depending on system speed. Upon completion, the compiled binaries incusd (daemon) and incus (client) appear in the current directory.

Installing Compiled Binaries

Move the binaries to system directories accessible from anywhere:

sudo cp incusd /usr/local/bin/
sudo cp incus /usr/local/bin/
sudo chmod 755 /usr/local/bin/{incusd,incus}

Verify installation:

/usr/local/bin/incus --version

Configuring Systemd Service for Source Build

Creating a systemd service file enables automatic daemon startup:

sudo bash -c 'cat > /etc/systemd/system/incus.service << EOF
[Unit]
Description=Incus Container Manager Daemon
Documentation=man:incusd(1)
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/incusd --group=incus
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF'

Reload systemd and start the service:

sudo systemctl daemon-reload
sudo systemctl start incus
sudo systemctl enable incus

Initial Configuration of Incus

After successful installation, Incus requires initial configuration to define storage backends, networking, and operational parameters.

Running the Interactive Configuration Wizard

Launch the interactive configuration script:

sudo incus admin init

This command presents a series of prompts asking about your preferred configuration. The wizard guides you through critical decisions affecting Incus behavior.

Selecting Storage Backend

The first major decision involves choosing a storage backend for container and VM images. Debian 13 supports four options:

• dir: Simple directory-based storage suitable for development. No special kernel features required, but performance is limited for high workloads.
• btrfs: Modern filesystem with snapshots and compression. Requires btrfs filesystem, offering good performance with reasonable overhead.
• lvm: Logical volume management backend ideal for production environments. Delivers excellent performance and scalability.
• zfs: Advanced filesystem providing maximum performance and flexibility. Requires ZFS installation, typically chosen by experienced administrators.

For most Debian 13 installations, btrfs provides the optimal balance between simplicity and performance. If your system already uses LVM, select the lvm backend to leverage existing infrastructure.

Configuring Networking

Incus requires a network bridge for container-to-host communication. The wizard prompts whether to create a default bridge (typically named “incusbr0”). Accept the default suggestion unless you have specific networking requirements. The bridge handles DHCP and DNS services for containers and VMs automatically.

Setting Cluster Options

Clustering enables multiple Incus systems to work together. For single-system installations, decline clustering at this stage. Advanced deployments can enable clustering later.

Reviewing Configuration Summary

The wizard displays your configuration choices for approval. Review carefully and confirm. Incus then initializes storage, creates networking bridges, and completes startup.

Configuring Sub-UID and Sub-GID Ranges

Unprivileged containers require proper sub-UID and sub-GID configuration for security and functionality.

Understanding Sub-UID/GID

Sub-UID and sub-GID are user and group ID ranges delegated to Incus for use within unprivileged containers. They enable containers to run with full functionality while restricting access to the host system. Each user running Incus needs an allocated range of at least 65,536 IDs.

Checking Current Configuration

Verify existing sub-UID and sub-GID allocations:

cat /etc/subuid
cat /etc/subgid

If entries for the root user already exist with sufficient ranges, no changes are needed.

Allocating Sub-UID and Sub-GID Ranges

For new configurations or insufficient ranges, add entries:

echo "root:100000:65536" | sudo tee -a /etc/subuid
echo "root:100000:65536" | sudo tee -a /etc/subgid

This allocates UIDs/GIDs 100000-165535 to the root user for use with unprivileged containers. The ranges must not overlap with existing allocations.

Verifying Allocation

Confirm the changes:

cat /etc/subuid
cat /etc/subgid

Both files should now display the allocated ranges. These settings persist across reboots automatically.

Accessing Incus as an Unprivileged User

Running Incus commands as a regular user (without sudo) requires proper group membership and permissions.

Adding Your User to the Incus Group

Grant your user account access to Incus:

sudo usermod -a -G incus $USER

This command adds your current user to the incus group, granting socket access for Incus communication.

Applying Group Membership Without Logout

Changes take effect immediately in new shell sessions but require activating the group in the current session:

newgrp incus

After this command, you can run incus commands without sudo. To verify, list instances:

incus list

This command displays configured containers and VMs without requiring elevated privileges.

Persistent Group Membership Configuration

To ensure group membership persists across sessions, log out completely and log back in. This forces the system to re-read group assignments from the user database.

Installing and Configuring the Incus Web UI

The Incus Web UI provides a graphical interface for managing containers and VMs.

Web UI Package Installation

Install the web UI component:

sudo apt install incus-ui

The package installs the necessary web interface files and dependencies. If using the Zabbly repository, include it in the initial installation command for consistency.

Enabling Web UI and Configuring Access

By default, Incus exposes the Web UI on the local system. To access it remotely, configure Incus to listen on network interfaces:

sudo incus config set core.https_address 0.0.0.0:8443

This command binds the HTTPS server to all network interfaces on port 8443. Port 8443 is standard for secure web access to avoid conflicts with other services.

Firewall Configuration

If a firewall is active, allow inbound connections to port 8443:

sudo ufw allow 8443/tcp

For iptables-based firewalls:

sudo iptables -A INPUT -p tcp --dport 8443 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

Accessing the Web Interface

Open your web browser and navigate to:

https://your-server-ip:8443

Replace “your-server-ip” with your Debian 13 system’s IP address. Accept the self-signed certificate warning (Incus uses self-signed certificates by default for security). The dashboard displays after authentication.

Initial Login and Authentication

First access requires creating initial credentials. Follow the on-screen prompts to establish an administrator account. Remember these credentials for future access.

Migrating from LXD to Incus

Existing LXD users can migrate their containers and VMs to Incus while preserving configuration and data.

Pre-Migration Verification and Backup

Before migration, verify LXD compatibility. Incus accepts LXD versions 4.0 through 5.18. Check your LXD version:

lxc --version

Back up critical configurations and data:

sudo lxd sql exec '.dump' | gzip > lxd-backup.sql.gz

This creates a compressed database backup containing all LXD configurations.

Stopping LXD Daemon

Halt the LXD service before migration:

sudo systemctl stop lxd

Verify it’s stopped:

sudo systemctl status lxd

The output should show “inactive (dead)”.

Running the Migration Tool

Install the migration utility if not already present:

sudo apt install incus-extra

Execute the migration:

sudo lxd-to-incus

The tool displays progress information and any migration issues. For typical installations with a few containers, migration completes in seconds.

Verifying Successful Migration

Confirm containers migrated correctly:

incus list

This displays all containers and VMs now under Incus control. Verify all expected instances appear in the listing.

Removing LXD After Successful Migration

Once migration is verified, uninstall LXD:

sudo apt remove --purge lxd lxd-client

This removes LXD packages and configuration files. The --purge flag ensures complete removal.

Verifying Incus Installation Success

Comprehensive verification confirms Incus operates correctly and is ready for production use.

Checking Incus Version and System Information

Display version information:

incus --version

Show detailed system status:

incus info

This command outputs hardware specifications, kernel details, storage pool information, and network configuration. Review the output carefully, ensuring all details match your system.

Listing Available Storage Pools and Networks

View configured storage:

incus storage list

Verify network bridges:

incus network list

Both commands should display at least one configured storage pool and one network interface.

Testing Container Deployment

Create a test container to verify full functionality:

incus launch images:debian/12 test-container

This command downloads a Debian 12 image and launches a container. The process takes 30-60 seconds depending on network speed. Upon completion:

incus list

The test container should appear in the output showing “RUNNING” status.

Accessing the Test Container

Connect to the container shell:

incus exec test-container -- bash

Execute commands within the container:

cat /etc/os-release

This confirms the container contains a functional Debian system.

Stopping and Removing the Test Container

Stop the container:

incus stop test-container

Remove it:

incus rm test-container

Testing VM Deployment (Optional)

If VM support is desired, test VM creation:

incus launch images:debian/12 test-vm --vm

QEMU VM startup takes longer than containers, typically 30-90 seconds. Monitor progress:

incus console test-vm

Press Enter to view the boot process. Once booted, stop and remove the test VM:

incus stop test-vm
incus rm test-vm

Post-Installation Best Practices and Configuration

Establishing proper administration practices ensures reliable, secure Incus operations.

Regular Updates and Patch Management

Keep Incus current to receive security patches and feature improvements. For Zabbly repository installations:

sudo apt update
sudo apt upgrade

This retrieves and installs available updates. Set automatic updates if your organization permits:

sudo apt install unattended-upgrades

Backup and Disaster Recovery Strategy

Implement regular backups of critical containers. Create snapshots for quick recovery:

incus snapshot create container-name backup-$(date +%Y%m%d)

This creates timestamped snapshots for version control and rollback capability.

Resource Limits and Quota Management

Define resource limits to prevent single containers from consuming excessive resources:

incus config device add container-name limits-disk disk pool=default path=/ size=20GB
incus config set container-name limits.memory=2GB
incus config set container-name limits.cpu=2

These commands restrict a container to 20GB disk, 2GB RAM, and 2 CPU cores respectively.

Network Security Configuration

Isolate containers on private network bridges. Configure firewall rules:

sudo ufw allow from 10.0.0.0/24 to any port 8443

This permits access to the Web UI only from a specific subnet, enhancing security.

Image and Profile Management

Create standardized profiles for common workloads:

incus profile create web
incus profile device add web root disk pool=default path=/
incus profile set web limits.memory=1GB

Apply profiles when launching instances:

incus launch images:debian/12 webserver --profile web

Troubleshooting Common Installation and Configuration Issues

Problem resolution techniques address frequently encountered issues.

GPG Key Verification Failures

If Zabbly repository GPG key errors occur during apt update:

sudo apt-key adv --recv-keys 2C5C5A8D

Replace the key ID with the actual key mentioned in the error. For persistent issues, re-download the key:

curl -fsSL https://zabbly.com/incus/incus.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/zabbly.gpg > /dev/null
sudo apt update

Package Not Found or Dependency Errors

If apt install incus reports missing packages:

sudo apt clean
sudo apt update
sudo apt install -f

The -f flag attempts to fix broken dependencies. If issues persist, manually specify versions:

sudo apt install incus=0.4.0-1~debian13

Incus Daemon Startup Failures

If the daemon fails to start, check systemd logs:

sudo journalctl -u incus -n 100 --no-pager

Review error messages carefully. Common causes include:

• Permission issues: Verify /var/lib/incus ownership
• Storage errors: Check storage pool status with incus storage info default
• Port conflicts: Verify ports 8443 and 8080 aren’t in use by other services

Sub-UID/GID Configuration Problems

If unprivileged containers fail with permission errors:

cat /etc/subuid /etc/subgid

Ensure allocations exist. If missing, add them as described previously.

Container Network Communication Failures

If containers can’t reach the network:

incus network show incusbr0

Verify the bridge exists and has correct configuration. Check host firewall:

sudo ufw status

Disable the firewall temporarily to test:

sudo ufw disable
sudo systemctl restart incus

Re-enable after confirming functionality:

sudo ufw enable

Advanced Configuration Topics

Sophisticated deployments benefit from deeper configuration customization.

Storage Backend Selection and Management

For high-performance environments, consider ZFS backend:

sudo apt install zfsutils-linux

During incus admin init, select ZFS when prompted. ZFS provides advanced snapshot management and performance monitoring:

zpool list
zfs list

For production LVM deployments, create dedicated volume groups:

sudo vgcreate incus-vg /dev/sdb

Allocate this volume group during Incus configuration.

Advanced Networking Setup

Create custom network bridges for specific workloads:

incus network create private-net ipv4.address=10.1.0.1/24 ipv4.nat=true

This creates a network bridge with NAT for isolated containers.

Resource Monitoring and Performance Tuning

Enable performance monitoring:

incus config set core.metrics.address=":9100"

This exposes Prometheus-compatible metrics for performance analysis.

Clustered Incus Deployments

For multiple-node setups, enable clustering:

sudo incus admin init --clustering

Cluster additional nodes:

sudo incus admin init
# Accept clustering at the prompt
# Copy the join token from the initial node
sudo incus cluster join <token>

Congratulations! You have successfully installed Incus. Thanks for using this tutorial for installing Incus container and virtual machine manager on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official Incus website.