Skip to main content
SmolVM runs your code inside a fast, secure virtual machine. Under the hood it uses Firecracker on Linux and QEMU on macOS — both are tools for running isolated virtual machines. You don’t need to pick one; SmolVM detects your platform automatically.

​
Quick install

Install SmolVM with a single command:
This installs everything you need (including Python), configures your machine, and verifies the setup.

​
Manual install

If you prefer to install step by step:
On supported Linux and macOS systems, pip install smolvm pulls in the matching smolvm-core wheel automatically — most users do not need Rust installed.
Linux may prompt for sudo during smolvm setup to install host dependencies (Firecracker, nftables, iproute2) and configure runtime permissions. On macOS, setup installs QEMU via Homebrew.
After setup on Linux, activate your new KVM group membership with newgrp kvm, or log out and back in.

​
Requirements

  • Ubuntu, Debian, or Fedora (other distributions work but smolvm setup may not install host dependencies automatically)
  • KVM support — the kernel feature that lets SmolVM run virtual machines. Check with ls /dev/kvm
  • x86_64 architecture
  • Python 3.10+
The backend is selected automatically based on your platform (Firecracker on Linux, QEMU on macOS). To force a specific backend:

​
Optional extras

Install extras for agent framework examples or the web dashboard:
If you only need SmolVM as a sandbox, the base pip install smolvm is all you need.

​
Troubleshooting

If /dev/kvm doesn’t exist, enable virtualization:
For cloud VMs, enable nested virtualization in your hypervisor settings.
Add your user to the kvm group and activate it:
Ensure Homebrew’s bin directory is in your PATH:
For golden-AMI builds, two-stage deploys, pinning the Firecracker version, and other non-default install paths, see the upstream installation guide.

​
Uninstall

The rm -rf command deletes all sandbox state and cached images. Skip it if you might reinstall SmolVM later and want to keep your cached base images.

​
Next steps

Quickstart

Run your first sandbox in minutes

Basic usage

Learn about VM configuration options

Custom images

Build your own VM images with custom tools

API reference

Explore the complete API
Last modified on May 28, 2026