Contributor Guide

See also: User Guide (Python API) and Under the Hood (QEMU flags).

Requirements

• Python 3.11+ and uv for the workspace and all packages
• Docker is required for building base images (Dockerfiles are compiled into qcow2 VM images)
• QEMU is required for integration tests and building overlay images (overlays boot a real VM). Install the bundled version with quicksand install qemu, or use a system QEMU on PATH.

Lint, type checking, and unit tests (poe ci) work without Docker or QEMU.

Dev setup

git clone https://github.com/microsoft/quicksand
cd quicksand
uv sync --all-packages --all-groups --all-extras
quicksand install qemu ubuntu    # needed for integration tests
uv run poe ci                       # lint + typecheck + tests

Before committing:

uv run poe fix && uv run poe check

Common tasks

Command	What it does
uv run poe fix	Auto-fix lint + formatting
uv run poe check	Lint + format check + type check
uv run poe test	Unit tests (no QEMU needed)
uv run poe test:integration	Integration tests (needs QEMU + images)
uv run poe test:smb	SMB server unit tests
uv run poe ci	Full CI: check + test