Spawns lightweight nixos vms in a shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples simplify examples Jan 29, 2019


  • Spawns a headless qemu virtual machines based on a vm.nix nixos module in the current working directory.
  • Mounts $HOME and the user's nix profile into the virtual machine
  • Provides console access in the same terminal window

Example vm.nix:

{ pkgs, ... }: {
  boot.kernelPackages = pkgs.linuxPackages_latest;

Start a virtual machine

To start a vm use:

$ nixos-shell

In this case nixos-shell will read vm.nix in the current directory. Instead of vm.nix, nixos-shell also accepts other modules on the command line.

$ nixos-shell some-nix-module.nix

Terminating the virtual machine

Type Ctrl-a x to exit the virtual machine.

You can also run the poweroff command in the virtual machine console:

$vm> poweroff

Or switch to qemu console with Ctrl-a c and type:

(qemu) quit

Port forwarding

To forward ports from the virtual machine to the host, override the QEMU_NET_OPTS environment variable. In this example the tcp port 2222 on the host is forwarded to port 22 in the virtual machine:

$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" nixos-shell

SSH login

Your keys are used to enable passwordless login for the root user. At the moment only ~/.ssh/, ~/.ssh/ and ~/.ssh/ are added automatically. Use users.users.root.openssh.authorizedKeys.keyFiles to add more.


By default qemu will allow at most 500MB of RAM, this can be increased using virtualisation.memorySize.

{ virtualisation.memorySize = "1024M"; }


To increase the CPU count use virtualisation.cores (defaults to 1):

{ virtualisation.cores = 2; }


To use graphical applications, add the NixOS option (see examples/vm-graphics.nix).


By default for user's convenience nixos-shell does not enable a firewall. This can be overridden by:

{ networking.firewall.enable = true; }

Shared folders

To mount anywhere inside the virtual machine, use the nixos-shell.mounts.extraMounts option.

  nixos-shell.mounts.extraMounts = {
    # simple USB stick sharing
    "/media" = /media;

    # override options for each mount
    "/var/www" = {
      target = ./src;
      cache = "none";

You can further configure the default mount settings:

  nixos-shell.mounts = {
    mountHome = false;
    mountNixProfile = false;
    cache = "none"; # default is "loose"

Available cache modes are documented in the 9p kernel module.

More configuration

Have a look at the virtualisation options NixOS provides.