systemd-nspawn is the lightweight container manager included with systemd that runs a command or a complete operating system inside an isolated directory tree, using Linux kernel namespaces and control groups. In Linux virtualization, it belongs to OS-level virtualization: containers share the host kernel instead of booting their own, so they start in about a second and consume almost no memory beyond the processes they run.
The tool is often described as chroot done properly. Like chroot, it switches the root directory, but it also isolates the process tree, hostname, IPC objects and optionally the network, mounts virtual file systems correctly and can boot a full init system inside the container. It is a standard part of most systemd-based distributions and needs no separate daemon.
How the nspawn container is built
When started, systemd-nspawn creates a new set of kernel namespaces for the child process and then executes either a shell, a single command, or, with the --boot option, the container’s own init process as PID 1. The container sees only its own root directory, its own process list and its own hostname, while the host retains full visibility of everything inside.
Resource limits come from control groups (cgroups). Each container is registered with systemd-machined as a machine and placed in its own scope or service unit, so limits such as MemoryMax= or CPUQuota= apply exactly as they would to any systemd service. The command machinectl then lists, starts, stops and logs into registered containers.
The following table shows which namespaces nspawn uses and what each one isolates.
| Namespace | What it isolates | Default behavior |
|---|---|---|
| Mount | File system tree and mount points | Always private |
| PID | Process numbering and visibility | Always private |
| UTS | Hostname and domain name | Always private |
| IPC | System V IPC and POSIX queues | Always private |
| Network | Interfaces, routing and firewall | Shared unless a network option is set |
| User | User and group ID mapping | Optional with --private-users |
| Cgroup | View of the cgroup hierarchy | Private on unified cgroup systems |
Key options and configuration files
Most behavior is controlled through command-line switches or an equivalent .nspawn settings file stored in /etc/systemd/nspawn/. Container images normally live in `/var/lib/machines/`, where machinectl and the template unit systemd-nspawn@.service expect to find them.
The table summarizes the options administrators use most often.
| Option | Purpose | Typical value |
|---|---|---|
| `-D` or `–directory` | Root directory of the container | /var/lib/machines/debian |
| `-i` or `–image` | Raw disk image instead of a directory | debian.raw |
| `-b` or `–boot` | Run the container’s init system | Enabled for full systems |
| `-n` or `–network-veth` | Private virtual Ethernet link | Enabled for isolated networking |
| `-U` or `–private-users` | User namespace ID mapping | pick for automatic ranges |
| `–bind` | Share a host directory | /srv/data:/data |
| `–ephemeral` | Discard changes on exit | Used for tests |
A root file system is usually prepared with a distribution bootstrap tool, for example debootstrap for Debian or dnf --installroot for Fedora, or downloaded with machinectl pull-tar. Because nspawn simply boots a directory, any distribution with a compatible userspace can run on any host kernel that supports the required features.
Comparison with other Linux virtualization tools
systemd-nspawn sits between the simplicity of chroot and the features of full container platforms, while differing fundamentally from full hypervisors such as KVM with QEMU. The table compares it with neighboring tools.
| Technology | Isolation type | Separate kernel | Main strength |
|---|---|---|---|
| chroot | Root directory only | No | Minimal and universal |
| systemd-nspawn | Namespaces and cgroups | No | Built into systemd, boots full systems |
| LXC and Incus | Namespaces and cgroups | No | Rich management, images and clustering |
| Docker and Podman | Namespaces and cgroups | No | Application images and registries |
| KVM with QEMU | Hardware virtualization | Yes | Strong isolation, any guest OS |
Compared with Docker or Podman, nspawn targets system containers rather than single-application containers: it expects a whole distribution with an init system and no layered image format. Compared with LXC or Incus, it offers fewer management features but needs no additional packages. Unlike a virtual machine, it cannot run a different kernel or a non-Linux guest.
Typical uses and choosing when to apply it
nspawn is chosen when a full Linux userspace is needed quickly and the host already runs systemd. Distribution developers use it to build and test packages in clean environments, and administrators use it to run legacy services on a newer host.
| Situation | Recommended choice | Reason |
|---|---|---|
| Clean package build root | nspawn with --ephemeral | Fresh state for every build |
| Testing another distribution | nspawn with --boot | Full init system in seconds |
| Untrusted multi-tenant workloads | KVM virtual machine | Kernel boundary gives stronger isolation |
| Distributing an application | Podman or Docker | Image registries and layered images |
| Recovering a broken system | nspawn on the mounted root | Better than chroot for systemd tools |
Security limits and common mistakes
The most important limitation is the shared kernel: a kernel vulnerability exploited inside the container affects the host. nspawn reduces this risk by dropping capabilities, applying a default Seccomp filter and supporting user namespaces, but its documentation itself warns that it is not a full security sandbox for hostile code.
- Running without `–private-users` means root inside the container maps to real root on the host, which greatly increases the impact of an escape.
- Forgetting the network option leaves the container on the host network stack, so services inside it bind directly to host interfaces.
- Booting an image without systemd-compatible init can hang or fail, because
--bootexpects a working PID 1. - Writable bind mounts of sensitive host paths undo isolation; prefer
--bind-rofor shared data. - Assuming cgroup limits apply automatically is wrong; limits must be set in the service unit or with
--property.
The short version
systemd-nspawn lets a Linux computer run another complete Linux system inside a folder, as if it were a separate machine. The second system has its own programs, users and name, but it borrows the engine, meaning the kernel, of the main computer.
Because nothing new has to boot from scratch, it starts almost instantly and uses very little memory. The trade-off is weaker separation than a real virtual machine: it is like a well-locked apartment inside a shared building rather than a separate house.
Where it makes a difference
A maintainer of an open source library on a Fedora workstation must confirm that a new release builds on Debian stable. Instead of installing a virtual machine, the maintainer runs debootstrap once to create a Debian tree in /var/lib/machines/debian of about 300 MB.
For each test, the maintainer starts systemd-nspawn --ephemeral -D /var/lib/machines/debian and runs the build script with the source tree attached through --bind-ro. The container is ready in under two seconds, the build runs at native speed, and every change disappears on exit. Across a week of release testing, this workflow replaces a 4 GB virtual machine and keeps every build reproducible.