Installation
See Under the Hood: Installation for how these packages map to QEMU binaries and disk images.
Install quicksand
pip install 'quick-sandbox[qemu,alpine,ubuntu]'This installs the core Python library, CLI, QEMU, and VM images. No native dependencies needed.
To declare it as a dependency in your pyproject.toml:
[project]
dependencies = [
"quick-sandbox[qemu,alpine,ubuntu]",
]Install QEMU and an image
Quicksand bundles its own QEMU, so no system install is needed. Use the quicksand install CLI to download platform-specific binaries and images.
quicksand install qemu # Bundled QEMU (~15MB on macOS ARM64)
quicksand install ubuntu # Ubuntu 24.04 headless (~340MB)That's enough to start using Quicksand:
from quicksand import Sandbox
async with Sandbox(image="ubuntu") as sb:
result = await sb.execute("echo hello")
print(result.stdout)Available packages
QEMU (quicksand install qemu)
| macOS ARM64 | Linux ARM64 | Linux x86_64 | Windows x86_64 | |
|---|---|---|---|---|
| Download | 14 MB | 15 MB | 15 MB | 43 MB |
| On disk | 58 MB | 60 MB | 53 MB | 124 MB |
Images
| Image | Depends on | Display | ARM64 download | ARM64 on disk | Boot p50 | Boot p95 |
|---|---|---|---|---|---|---|
alpine | — | No | 73 MB | 74 MB | 0.37s | 0.45s |
ubuntu | — | No | 341 MB | 346 MB | 0.88s | 0.91s |
alpine-desktop | alpine | Yes | 287 MB | 290 MB | 0.47s | 0.54s |
ubuntu-desktop | ubuntu | Yes | 252 MB | 257 MB | 0.90s | 0.96s |
quicksand-agent | ubuntu | No | ~304 MB | ~308 MB | 0.91s | 0.92s |
quicksand-cua | quicksand-agent | No | ~445 MB | ~450 MB | 0.85s | 1.01s |
Boot times measured on macOS ARM64 (Apple M3 Max, HVF) with quicksand benchmark -n 5. First boot is slower due to cold cache.
quicksand install all installs QEMU and all images.
Alpine is smaller and boots faster. Ubuntu has a larger package ecosystem. Desktop images are overlays on their base image and add a graphical environment for screenshot/keyboard/mouse interaction. The agent sandbox images are pre-configured agent environments with Python 3.12, browser automation tools, and common AI agent dependencies.
Verify the installation
import asyncio
from quicksand import Sandbox
async def main():
async with Sandbox(image="ubuntu") as sb:
result = await sb.execute("uname -a")
print(result.stdout)
asyncio.run(main())If this prints a Linux kernel version, everything is working.
Requirements
- Python 3.11+
- macOS, Linux, or Windows. Hardware acceleration is auto-detected (HVF on macOS, KVM on Linux, WHPX on Windows). Software emulation (TCG) is used as a fallback but is much slower.
- No root/admin. QEMU runs as a normal user process.
- No Docker. Quicksand is not container-based (Docker is only needed for building new images, not running them).
Using system QEMU
If you already have QEMU installed, Quicksand will find it on PATH as a fallback. But the bundled QEMU (quicksand install qemu) is recommended. It's tested and includes the right firmware files.