Skip to main content

​
Installation

SmolVM supports two backends depending on your platform:
  • Linux: Firecracker (KVM-based, production-ready)
  • macOS: QEMU (development and testing)

​
Prerequisites

  • Operating System: Ubuntu, Debian, or Fedora
  • KVM Support: Your system must support hardware virtualization
  • Python: 3.10 or higher
Check if KVM is available by running lsmod | grep kvm. You should see either kvm_intel or kvm_amd.

​
Install SmolVM

1

Install the Python package

Install SmolVM using pip:
pip install smolvm
2

Configure system dependencies

Run the system setup script to install Firecracker and configure runtime permissions:
sudo ./scripts/system-setup.sh --configure-runtime
This script will:
  • Install Firecracker and Jailer binaries
  • Configure required system permissions
  • Set up networking capabilities
  • Optionally install Docker (if needed for custom images)
# Check prerequisites without installing
sudo ./scripts/system-setup.sh --check-only

# Install with Docker support
sudo ./scripts/system-setup.sh --configure-runtime --with-docker

# Skip dependency installation (if already installed)
sudo ./scripts/system-setup.sh --skip-deps

# Remove runtime configuration
sudo ./scripts/system-setup.sh --remove-runtime-config
3

Verify installation

Verify that SmolVM is installed correctly:
smolvm doctor --backend firecracker
The doctor command will check:
  • Backend availability (Firecracker or QEMU)
  • KVM support (Linux only)
  • Network configuration
  • SSH utilities
For CI-friendly output, use smolvm doctor --json --strict

​
Post-installation

Once installed, you can:

Start the quickstart

Create your first VM

Run demos

smolvm demo list
smolvm demo simple

​
Troubleshooting

If you see KVM-related errors:
  1. Check if KVM modules are loaded: 
    lsmod | grep kvm
  2. Ensure your CPU supports virtualization (Intel VT-x or AMD-V)
  3. Enable virtualization in your BIOS/UEFI settings
  4. Load the KVM module: 
    sudo modprobe kvm
sudo modprobe kvm_intel  # or kvm_amd for AMD
If you encounter permission errors:
  1. Re-run the setup script with --configure-runtime: 
    sudo ./scripts/system-setup.sh --configure-runtime
  2. Log out and back in for group changes to take effect
  3. Verify your user has the necessary permissions: 
    groups  # Should include kvm, docker (if installed)
If QEMU is not found:
  1. Ensure Homebrew is installed: 
    brew --version
  2. Install QEMU manually: 
    brew install qemu
  3. Verify installation: 
    qemu-system-aarch64 --version
# or
qemu-system-x86_64 --version

Build docs developers (and LLMs) love

Get started for freeTalk to us