systemd-nspawn(1)
Spawn and manage lightweight containers with systemd, providing process and resource isolation.
Synopsis
systemd-nspawn [OPTION]... [COMMAND] [ARG]...Description
systemd-nspawn is a tool for spawning and managing lightweight containers and virtual machines. It uses Linux namespaces and cgroups to isolate a process tree from the host system, providing filesystem, network, user ID, and process isolation. It's commonly used for testing, development, or running services in isolated environments.
The container shares the kernel with the host but has its own root filesystem, process namespace, and optionally its own network stack. It integrates tightly with systemd, allowing containers to run systemd as their init system or PID 1 process.
systemd-nspawn can boot a full operating system image or simply run a shell or application inside an isolated environment. It's lighter than full virtualization but more isolated than chroot.
Common options
| Flag | What it does |
|---|---|
-D, --directory=PATH | Use PATH as the root filesystem for the container instead of the host root |
-i, --image=IMAGE | Use a disk image (raw, qcow2, or other formats) as the container root filesystem |
-u, --user=USER | Run the container with the specified user or UID; enables user namespace mapping |
--private-network | Create a private network namespace; container gets a loopback interface only |
--network-veth | Create a virtual Ethernet link between host and container network interfaces |
-b, --boot | Boot the container as a full OS; container runs systemd as PID 1 |
-E, --setenv=VAR=VALUE | Set environment variables inside the container |
--bind=PATH[:PATH[:OPTS]] | Bind-mount a host directory into the container (read-only if :ro specified) |
--bind-ro=PATH[:PATH] | Bind-mount a host directory as read-only inside the container |
--tmpfs=PATH:SIZE | Mount a tmpfs filesystem at PATH inside the container with optional size limit |
--machine=NAME | Set the container name; useful for tracking and systemd integration |
--capability=CAP | Keep specified Linux capability in the container (e.g., CAP_SYS_ADMIN) |
Examples
Spawn an interactive bash shell inside the container rooted at /var/lib/machines/ubuntu
systemd-nspawn -D /var/lib/machines/ubuntu /bin/bashRun a shell as 'user' with private network namespace, isolated from host networking
systemd-nspawn -D /srv/chroot -u user --private-network /bin/shBoot a full operating system in the container; systemd runs as PID 1 with machine name 'myvm'
systemd-nspawn -D /mnt/os -b --machine=myvmMount the host's /home/user as read-only at /mnt/shared inside the container
systemd-nspawn -D /var/lib/machines/debian --bind=/home/user:/mnt/shared:ro /bin/bashBoot a disk image as a container with virtual Ethernet link to the host
systemd-nspawn -i /var/lib/machines/ubuntu.raw -b --network-vethRun a single application (myapp) as 'appuser' with a custom environment variable
systemd-nspawn -D /srv/app -u appuser -E LISTEN_PID=1 /usr/bin/myappCreate isolated tmpfs mounts for /tmp and /run with specific size limits
systemd-nspawn -D /tmp/test --tmpfs=/tmp:1G --tmpfs=/run:512M /bin/bashStart a registered container via systemd service unit (requires proper image setup)
systemctl start [email protected]