systemd-nspawn

On this page 7

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.

NamespaceWhat it isolatesDefault behavior
MountFile system tree and mount pointsAlways private
PIDProcess numbering and visibilityAlways private
UTSHostname and domain nameAlways private
IPCSystem V IPC and POSIX queuesAlways private
NetworkInterfaces, routing and firewallShared unless a network option is set
UserUser and group ID mappingOptional with --private-users
CgroupView of the cgroup hierarchyPrivate on unified cgroup systems
Namespaces used by systemd-nspawn

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.

OptionPurposeTypical value
`-D` or `–directory`Root directory of the container/var/lib/machines/debian
`-i` or `–image`Raw disk image instead of a directorydebian.raw
`-b` or `–boot`Run the container’s init systemEnabled for full systems
`-n` or `–network-veth`Private virtual Ethernet linkEnabled for isolated networking
`-U` or `–private-users`User namespace ID mappingpick for automatic ranges
`–bind`Share a host directory/srv/data:/data
`–ephemeral`Discard changes on exitUsed for tests
Frequently used systemd-nspawn options

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.

TechnologyIsolation typeSeparate kernelMain strength
chrootRoot directory onlyNoMinimal and universal
systemd-nspawnNamespaces and cgroupsNoBuilt into systemd, boots full systems
LXC and IncusNamespaces and cgroupsNoRich management, images and clustering
Docker and PodmanNamespaces and cgroupsNoApplication images and registries
KVM with QEMUHardware virtualizationYesStrong isolation, any guest OS
systemd-nspawn compared with related technologies

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.

SituationRecommended choiceReason
Clean package build rootnspawn with --ephemeralFresh state for every build
Testing another distributionnspawn with --bootFull init system in seconds
Untrusted multi-tenant workloadsKVM virtual machineKernel boundary gives stronger isolation
Distributing an applicationPodman or DockerImage registries and layered images
Recovering a broken systemnspawn on the mounted rootBetter than chroot for systemd tools
Decision guide for systemd-nspawn

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 --boot expects a working PID 1.
  • Writable bind mounts of sensitive host paths undo isolation; prefer --bind-ro for 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.