NixOS Test Driver Manual

Practical guidance for building, debugging, and scaling NixOS integration tests.

The NixOS test driver is the framework behind the integration tests used throughout nixpkgs, where it orchestrates networks of virtual machines and other test environments. This manual is the hands-on companion to the official documentation: opinionated, example-driven, and focused on helping you get productive quickly.

New here? Start with Setup. Need a working example? Go to Tutorials.

• Model real systems

  Test one machine or whole networks of services with reproducible infrastructure.

• Debug failures interactively

  Keep machines alive, log in, inspect state, and turn flaky CI failures into something you can reason about.

• Use the same tooling as nixpkgs

  Learn the framework that powers the upstream NixOS integration test suite.

Browse the Manual

• Setup

  ---

  Install the prerequisites and get your first test running.

• Tutorials

  ---

  Learn by example: minimal tests, networking, interactive debugging, graphics, overlays, and more.

• Features

  ---

  Browse the driver's capabilities in focused reference-style guides.

• Best Practices

  ---

  Pick up patterns that make tests faster, clearer, and more reliable in CI.

Choose Your Path

• I want to get started

  Start with Setup, then continue with A minimal test.

• I need to debug a failing test

  Go to Interactive test driver, Connect to nodes via SSH/VSOCK, and Breakpoint hook.

• I want examples I can adapt

  Browse the Tutorials for multi-node, graphical, CUDA, and overlay-based test setups.

• I want production-grade patterns

  Read the Best Practices for timeouts, synchronization, portability, and multi-node parallelism.

Why This Manual?

The official NixOS manual is the authoritative reference for the test driver. This manual complements it with a different goal:

• explain the driver in a more guided and opinionated way
• show realistic examples instead of only listing options
• collect operational advice from day-to-day work with real test suites

If you already know the reference, this manual helps you move faster. If you are new to the test driver, it gives you a clearer path through the material.

How It Fits Together

The test driver coordinates declarative machine setup with imperative test execution.

Maintained in Practice

This manual is maintained by the Applicative Systems Group, which contributes to and works with the NixOS test-driver ecosystem in production settings.

The Python test driver that became the standard implementation in nixpkgs was authored by Jacek Galowicz (@tfc) together with collaborators and later adopted across the NixOS test suite. Since then, the ecosystem has continued to grow with further work such as container support and broader operational guidance.

• Applicative Systems Group

  

  Maintains practical expertise around the NixOS test-driver ecosystem, CI workflows, and advanced test infrastructure.

• Jacek Galowicz (@tfc)

  Author of the Python test driver and curator of this manual.

If you need help with NixOS integration testing, CI, or custom test infrastructure:

• contact hello@applicative.systems
• join the Applicative Systems Matrix channel
• report issues on GitHub

Background

The NixOS test driver has a long history in nixpkgs:

• the original VM test framework was introduced in 2009: original commit
• the Python driver was introduced in 2019 by Jacek Galowicz (@tfc) together with Julian Stecklina (@blitz) and Jana Traue (@jtraue), and became the standard implementation: original commit
• container support was added in 2026 by Jacek Galowicz (@tfc), Kierán Meinhardt (@kmein), and Jeremy Fleischman (@jfly), based on a first implementation by the Clan project. Special thanks go to Maximilian Bosch (@ma27).

The driver is used by 1000+ tests in nixpkgs and also sees substantial downstream use beyond upstream NixOS itself.

Further references

• Mastering NixOS Integration Tests Part 1

  ---

  

  A deep dive into the test driver architecture and how to structure larger test suites.

  Visit

• Mastering NixOS Integration Tests Part 2

  ---

  

  Interactive debugging, OCR, and practical techniques for productive test development.

  Visit

• Faster, Cheaper NixOS Integration Tests

  ---

  

  Using containers to accelerate integration testing without sacrificing the isolation of full virtual machines.

  Visit

• Running Integration Tests on macOS

  ---

  

  Cross-platform developer workflows for running NixOS integration tests on Apple Silicon.

  Visit

• NixOS Integration Tests on GitHub Actions

  ---

  

  Bringing the test driver into modern CI pipelines on GitHub Actions.

  Visit

• NixCon Talk: Mastering NixOS Integration Tests

  ---

  

  Slides and examples from the NixCon and Planet Nix workshop on the test driver.

  Visit