nixos-container

List running containers

$ sudo nixos-container list

$ sudo nixos-container create [container_name] --config-file [nix_config_file_path]

$ sudo nixos-container [start|stop|terminate|destroy|status] [container_name]

$ sudo nixos-container run [container_name] -- [command] [command_arguments]

$ sudo $EDITOR /var/lib/container/[container_name]/etc/nixos/configuration.nix && sudo nixos-container update [container_name]

$ sudo nixos-container root-login [container_name]

nixos-container COMMAND [OPTIONS] [ARGUMENTS]

Examples:
nixos-container create my-container
nixos-container start my-container
nixos-container enter my-container --root -- /bin/bash
nixos-container list

--help
    Display help information for the command or a specific subcommand.

--show-trace
    Show a stack trace on error (a common Nix/NixOS option).

create --auto-start
    Start the newly created container immediately after creation.

create --ephemeral
    Mark the container as ephemeral; it will be destroyed when stopped.

create --force
    Force the creation of a container, potentially overwriting an existing one.

destroy --force
    Force the destruction of a container, even if it's running.

enter --root
    Enter the container as the root user. By default, it uses the current user.

enter --set-env
    Set an environment variable for the command executed inside the container.

pull-config --switch
    After pulling the configuration, activate it inside the container.

The nixos-container command-line tool provides a declarative interface for managing lightweight containers on NixOS. Leveraging systemd-nspawn internally, it extends its capabilities with the power of NixOS's reproducible configuration management. Users define their containers, including their networking, state persistence, and internal NixOS configuration, directly within their main NixOS system configuration (typically /etc/nixos/configuration.nix).

This approach enables highly reproducible, version-controlled container environments ideal for service isolation, development sandboxes, or testing. nixos-container simplifies common tasks such as container creation, starting, stopping, entering, and destruction, integrating seamlessly with the NixOS build and activation process. Unlike tools like Docker, nixos-container focuses on encapsulating full NixOS systems, managed purely declaratively, rather than isolated application layers. It supports both privileged and unprivileged (rootless) operations, offering flexibility for various use cases while maintaining the strong guarantees of the Nix ecosystem.

Built upon systemd-nspawn, not a full virtual machine or a Docker-style layered image system.
Requires NixOS as the host operating system.
Networking configuration (e.g., bridged, host, private) can be complex and requires careful setup in the NixOS configuration.
Rootless containers, while supported, may have certain limitations depending on kernel features and host system configuration.
Container state persistence is governed by the stateDir option in the container's NixOS configuration.
Debugging services inside containers might require specific tools and understanding of systemd-nspawn logging.

The primary functionality of nixos-container is accessed via subcommands:
create <name>: Builds and initializes a new container based on its NixOS declaration.
start <name>: Starts a configured container.
stop <name>: Stops a running container.
status <name>: Displays the current status of a container.
enter <name> [-- command...]: Enters a running container's shell or executes a specific command inside it.
destroy <name>: Permanently removes a container and its associated state.
list: Lists all containers defined in the NixOS configuration.
rootless-install: Prepares the host system for running rootless containers for the current user.
pull-config <name>: Pulls the latest host configuration into the container, allowing it to reconfigure itself.

Containers managed by nixos-container are defined declaratively in the host's /etc/nixos/configuration.nix or an imported module. An example definition typically looks like:
containers.my-web-server = {
config = {
system.stateVersion = "23.11";
networking.hostName = "web-server";
# ... other NixOS options for the container ...
};
autoStart = true;
privateNetwork = true;
# ... other container-specific options ...
};
This configuration is then applied via nixos-rebuild switch on the host, which prepares the container environments.

Containers can be configured with various networking modes:
privateNetwork: Creates a private network for the container with NAT to the host's network.
hostAddress / containerAddress: Defines specific IP addresses for the host and container within the private network.
extraHostPaths: Allows mounting paths from the host into the container.
bindHost: Binds a specific host IP address to the container.
network: Connects the container to a specific network bridge on the host.

The nixos-container tool emerged as a natural evolution of NixOS's declarative approach to system management, extending it to lightweight containerization. Initially, NixOS users leveraged systemd-nspawn directly. However, the need for a more integrated, declarative, and reproducible way to manage these containers led to the development of nixos-container. Its focus has always been on providing a seamless experience within the NixOS ecosystem, allowing container definitions to be part of the host's central configuration.nix. Significant development has included improvements in networking capabilities and the introduction of robust rootless container support, making it a powerful tool for creating isolated, reproducible environments.

systemd-nspawn(1), nix(1), nixos-rebuild(1), systemd(1), docker(1)