NixOS VM Builder for Windows Users

This guide helps Windows users create NixOS virtual machines without installing Nix locally. Using Docker, you can build customized NixOS VMs that work with popular virtualization platforms on Windows.

Overview

The NixOS VM Builder provides:

Quick Start (Pre-built Images)

Option 1: Download Pre-built VMs

  1. Visit Releases: Go to GitHub Releases

  2. Choose Template: Download your preferred VM template:
    • nixos-desktop-virtualbox.ova - Full desktop environment
    • nixos-server-virtualbox.ova - Headless server
    • nixos-gaming-virtualbox.ova - Gaming-optimized
    • nixos-minimal-virtualbox.ova - Lightweight installation
    • nixos-development-virtualbox.ova - Development environment

  3. Import VM: Use your virtualization software to import the downloaded file

  4. Login: Default credentials are nixos / nixos (change immediately!)

Option 2: Build Custom VMs with Docker

Prerequisites

Build Your First VM

  1. Open PowerShell and create a workspace:

    mkdir nixos-vms
cd nixos-vms

  2. Pull the builder image:

    docker pull olafkfreund/nixos-vm-builder:latest

  3. Build a desktop VM:

    docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest virtualbox --template desktop

  4. Find your VM: Check the output/ directory for the generated .ova file

VM Templates

Desktop Template (desktop)

Perfect for: New NixOS users, general desktop use

Includes:

Import Instructions:

Server Template (server)

Perfect for: Headless servers, learning Linux administration

Includes:

Access: SSH to VM IP address with nixos user

Gaming Template (gaming)

Perfect for: Gaming on NixOS, Steam gaming

Includes:

Note: Requires GPU passthrough for best performance

Minimal Template (minimal)

Perfect for: Learning NixOS basics, resource-constrained environments

Includes:

Use Case: Perfect for learning NixOS without GUI overhead

Development Template (development)

Perfect for: Software development, programming

Includes:

Virtualization Platform Setup

  1. Download VirtualBox: virtualbox.org

  2. Install Extension Pack for better performance

  3. Import OVA:
    • File → Import Appliance
    • Select your nixos-*.ova file
    • Adjust VM settings if needed
    • Click Import
  4. First Boot:
    • Start the VM
    • Login with nixos / nixos
    • Change password: passwd

Hyper-V (Windows Pro/Enterprise)

  1. Enable Hyper-V:

    Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
  2. Hyper-V Manager:
    • Open Hyper-V Manager
    • Action → New → Virtual Machine
    • Use existing virtual hard disk
    • Select your nixos-*.vhdx file
  3. VM Settings:
    • Enable Dynamic Memory
    • Set appropriate CPU cores
    • Connect to virtual switch

VMware Workstation/Player

  1. Create New VM:
    • File → New Virtual Machine
    • Select “I will install the operating system later”
    • Choose Linux → Other Linux
  2. Add Disk:
    • Remove default disk
    • Add existing disk
    • Select your nixos-*.vmdk file
  3. VM Settings:
    • Adjust memory and CPU
    • Enable virtualization features

QEMU (Advanced Users)

# Install QEMU for Windows
winget install qemu

# Run VM
qemu-system-x86_64 -m 4096 -hda nixos-desktop.qcow2 -enable-kvm

Building Custom VMs

Basic Build Commands

# Build specific template and format
docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest <FORMAT> --template <TEMPLATE>

# Examples:
docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest virtualbox --template desktop
docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest hyperv --template server
docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest vmware --template gaming

Advanced Build Options

# Custom VM specifications
docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest virtualbox `
  --template desktop `
  --disk-size 40960 `
  --memory 8192 `
  --vm-name my-custom-desktop

# Build all formats at once
docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest all --template development

# List available templates
docker run --rm olafkfreund/nixos-vm-builder:latest --list-templates

# Validate configuration only
docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest --validate-only --template server

Custom Configuration Files

  1. Create custom config:

    # Create custom-config.nix in your workspace
@"
{ config, pkgs, lib, ... }:
{
  # Your custom NixOS configuration
  environment.systemPackages = with pkgs; [
    firefox
    git
    docker
  ];

  services.openssh.enable = true;
}
"@ | Out-File -FilePath custom-config.nix -Encoding utf8

  2. Build with custom config:

    docker run --rm -v "${PWD}:/workspace" olafkfreund/nixos-vm-builder:latest virtualbox `
  --config /workspace/custom-config.nix

Troubleshooting

Build Issues

Problem: Docker build fails with “out of space” Solution: Increase Docker Desktop disk space in settings

Problem: Build takes very long Solution:

Problem: VM doesn’t boot Solution:

VM Performance

Slow Performance:

Graphics Issues:

Network Issues

No Internet Access:

SSH Connection Failed:

Security Best Practices

Initial Setup

  1. Change Default Password:

    passwd nixos

  2. Update System:

    sudo nixos-rebuild switch --upgrade

  3. Configure SSH Keys (for server VMs):

    # Generate SSH key on Windows
ssh-keygen -t ed25519

# Copy to VM
ssh-copy-id nixos@vm-ip-address

  4. Enable Firewall:

    sudo systemctl enable firewall
sudo systemctl start firewall

Production Considerations

Next Steps

Learning NixOS

  1. Official Manual: NixOS Manual
  2. Community Wiki: NixOS Wiki
  3. Package Search: search.nixos.org

Advanced Usage

  1. Flakes: Modern NixOS configuration management
  2. Home Manager: User environment management
  3. Development Shells: Project-specific development environments
  4. Custom Packages: Creating your own Nix packages

Community

FAQ

Q: Do I need to install Nix on Windows?

A: No! The Docker-based builder handles everything. You only need Docker Desktop.

Q: Can I run NixOS alongside Windows?

A: Yes! These are virtual machines that run inside Windows. You can also dual-boot, but VMs are safer for learning.

Q: Which template should I choose?

A:

Q: How much disk space do I need?

A:

Q: Can I modify the templates?

A: Yes! Fork the repository and customize the template files, or create your own configuration files.

Q: Is this secure for production use?

A: The VMs use default passwords and are configured for ease of use. For production, change all passwords, configure SSH keys, and apply security hardening.

Q: Can I run multiple VMs?

A: Yes! Each VM is independent. Just ensure you have enough system resources.

Need Help?

Built with NixOS and Docker