Home

Incus Reference Guide

Modern container and virtual machine manager

What is Incus?

Incus is a modern, powerful system container and virtual machine manager that enables you to run full Linux systems in isolated environments. As a community-driven fork of LXD, Incus provides a unified experience for managing both lightweight system containers and full virtual machines on a single host.

Whether you're building a private cloud infrastructure, creating isolated development environments, or spinning up quick debugging machines, Incus delivers enterprise-grade virtualization with remarkable simplicity. It's perfect for running production workloads, testing applications in clean environments, or experimenting with different operating systems without the overhead of traditional virtualization.

Nested Virtualization: VMs Inside VMs

One of Incus's most powerful features is its support for nested virtualization. This allows you to run virtual machines inside other virtual machines, opening up possibilities that were previously complex or impossible:

  • Testing hypervisor configurations: Develop and test virtualization setups without dedicated hardware
  • Multi-layer isolation: Create sophisticated sandbox environments with multiple levels of security boundaries
  • Cloud development: Build and test cloud-native infrastructure locally by simulating multi-node clusters within VMs
  • Training and education: Provide students with full virtualization stacks for learning without requiring bare metal access
  • CI/CD pipelines: Run automated tests that require VM capabilities inside ephemeral test environments

With nested virtualization, you can launch an Incus VM, install Incus inside it, and create additional containers or VMs within that nested environment—all with native performance characteristics.

Core Capabilities

System Containers (LXC)

Lightweight, OS-level virtualization that runs multiple isolated Linux systems on a single host.

  • Near-native performance
  • Minimal overhead
  • Instant boot times
  • High density deployment

Virtual Machines (QEMU)

Full hardware virtualization supporting any operating system including Windows and non-Linux OSes.

  • Strong isolation
  • Run any OS
  • Nested virtualization support
  • Live migration capable

Unified Management

Single CLI and API for managing both containers and VMs with the same commands.

  • Consistent interface
  • RESTful API
  • Cross-platform clients
  • Automation friendly

Storage Management

Flexible storage backends with ZFS, Btrfs, LVM, and directory-based options.

  • Built-in snapshots
  • Copy-on-write support
  • Storage pools
  • Volume management

Advanced Networking

Software-defined networking with bridges, VLANs, and overlay networks.

  • Multiple network types
  • IP address management
  • DNS integration
  • Network forwarding

Live Migration

Move running instances between hosts without downtime for maintenance and load balancing.

  • Zero-downtime migrations
  • Cluster support
  • Stateful transfers
  • Automatic failover

Use Cases

1. Private Cloud Infrastructure

Deploy your own cloud infrastructure with multi-tenancy, API-driven automation, and enterprise features without licensing costs. Perfect for organizations needing on-premises infrastructure with cloud-like capabilities.

2. Development & Testing

Create isolated, reproducible development environments in seconds. Test across multiple OS distributions, kernel versions, and configurations without affecting your host system.

3. CI/CD Infrastructure

Run build agents, test suites, and deployment targets in ephemeral, isolated environments. Scale horizontally by spinning up instances on-demand and destroying them when done.

4. Debugging & Troubleshooting

Quickly replicate production environments to debug issues. Create snapshots before testing risky changes, rollback instantly if something goes wrong.

5. Learning & Experimentation

Safely explore new technologies, test dangerous commands, or learn system administration without risk to your host. Perfect for training environments and educational institutions.

6. Microservices & Application Hosting

Deploy microservices in lightweight containers or run containerized applications with strong isolation. Ideal for edge computing and resource-constrained environments.

Key Features

Feature Description Benefits
Image Server Access thousands of pre-built images Ubuntu, Debian, Alpine, CentOS, and more
Profiles Reusable configuration templates Consistent deployments, easy scaling
Projects Isolation and multi-tenancy Separate resources per team/workload
Snapshots Point-in-time backups Quick rollback, testing safety
Resource Limits CPU, memory, disk quotas Fair sharing, prevent resource hogging
Remote API Full REST API Automation, integration, custom tools

Why Choose Incus?

Advantages Over Alternatives

  • vs Docker: Full system containers, not just application containers. Run complete OS with systemd, multiple processes, SSH access
  • vs VirtualBox: Headless operation, API-driven, better resource efficiency, production-ready clustering
  • vs Proxmox: Simpler architecture, no web UI overhead, better suited for single-host or small clusters
  • vs OpenStack: Far less complex, minimal dependencies, easier to deploy and maintain
  • Community-Driven: Open governance, active development, no vendor lock-in

Getting Started

Incus is available for most Linux distributions. Installation is straightforward, and you can have your first instance running within minutes.

Quick Start

# Install Incus (varies by distribution)
apt install incus  # Debian/Ubuntu
dnf install incus  # Fedora
pacman -S incus    # Arch Linux

# Initialize Incus
incus admin init

# Launch your first container
incus launch images:ubuntu/22.04 my-container

# Launch a virtual machine
incus launch images:ubuntu/22.04 my-vm --vm

# Access the instance
incus exec my-container -- bash

Explore the other sections of this guide to learn about Incus architecture, detailed comparisons between containers and VMs, clustering capabilities, and comprehensive command references.

Virtualization Platforms