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 packages (nftables, iproute2) and configure runtime permissions. Firecracker itself installs into your home directory at ~/.smolvm/bin, so it needs no system folders. 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.

​
Choose where Firecracker is installed

On Linux, smolvm setup installs Firecracker into ~/.smolvm/bin for the user who runs the command. The install is atomic: SmolVM stages the binary in a temporary file and moves it into place, so a partially downloaded binary never replaces a working one. If a firecracker binary is already on your PATH, SmolVM keeps using it and does not install a duplicate. To install into a different folder for one setup run, pass --firecracker-dir:
If that folder is not on your PATH, set SMOLVM_FIRECRACKER_DIR so later SmolVM commands can find the binary:
SmolVM looks for Firecracker in this order:
  1. The --firecracker-dir flag, if passed.
  2. The SMOLVM_FIRECRACKER_DIR environment variable. When either of these is set, SmolVM only looks in that folder.
  3. Any firecracker binary on PATH.
  4. The per-user default, ~/.smolvm/bin/firecracker.
This setting changes only where Firecracker lives. Images and sandbox state stay in their usual locations.

​
Fedora Atomic desktops

Silverblue, Bluefin, and other Fedora Atomic systems work with the normal smolvm setup command when the required host tools are already installed. SmolVM never modifies the rpm-ostree deployment itself. If a required tool is missing, setup prints the exact sudo rpm-ostree install command to run, and asks you to reboot before retrying.

​
Install from source

Build SmolVM from source when you want the latest unreleased changes, or when you plan to modify SmolVM itself. This compiles the Rust helper package (smolvm-core) locally instead of downloading a prebuilt wheel. You need Git, uv (the Python package manager SmolVM uses), and the Rust toolchain.
1

Clone the repository

2

Build and install

This creates a virtual environment, installs SmolVM’s dependencies, and compiles smolvm-core from the Rust sources in the checkout.
Confirm the local build loaded correctly:
It prints a report of the native helpers available on your machine.
3

Set up the host and verify

smolvm setup installs host dependencies — Firecracker on Linux, QEMU on macOS — and configures permissions. smolvm doctor confirms your machine is ready to run sandboxes.
Run source-built commands with uv run smolvm ... from the repository directory, so they use the build in your checkout. To use a plain smolvm command instead, activate the environment with source .venv/bin/activate.
Rebuild after changing Rust code with uv sync --reinstall-package smolvm-core, then rerun uv run python -m smolvm_core to confirm Python loads your new build.
For contribution guidelines, tests, and code style checks, see CONTRIBUTING.md.

​
Requirements

  • Ubuntu, Debian, or Fedora. smolvm setup installs missing host packages with apt or dnf. On rpm-ostree systems such as Fedora Atomic, it prints the rpm-ostree command to run instead. Other distributions work but you may need to install host dependencies yourself
  • KVM support — the kernel feature that lets SmolVM run virtual machines. Check with ls /dev/kvm
  • x86_64 architecture
  • Python 3.10+
When SMOLVM_BACKEND is unset or auto, SmolVM picks the best backend that is actually installed on your machine. It prefers Firecracker on Linux and QEMU on macOS, and falls back through Firecracker → QEMU → libkrun so it never resolves to a hypervisor your host cannot run. If nothing suitable is installed, smolvm sandbox create fails immediately with a plain-English message telling you what to install — before downloading the base image, so a missing hypervisor no longer costs you a multi-hundred-MB download. 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 August 29, 2026