> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install SmolVM on Linux or macOS

> Install SmolVM on Linux or macOS using the install script or pip — sets up the Firecracker or QEMU backend automatically based on your platform.

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:

```bash theme={null}
curl -sSL https://celesto.ai/install.sh | bash
```

This installs everything you need (including Python), configures your machine, and verifies the setup.

## Manual install

If you prefer to install step by step:

```bash theme={null}
pip install smolvm
smolvm setup
smolvm doctor
```

On supported Linux and macOS systems, `pip install smolvm` pulls in the matching `smolvm-core` wheel automatically — most users do not need Rust installed.

<Note>
  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.
</Note>

After setup on Linux, activate your new KVM group membership with `newgrp kvm`, or log out and back in.

## Requirements

<Tabs>
  <Tab title="Linux">
    * 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+
  </Tab>

  <Tab title="macOS">
    * macOS on Apple Silicon or Intel
    * [Homebrew](https://brew.sh)
    * Python 3.10+
  </Tab>
</Tabs>

The backend is selected automatically based on your platform (Firecracker on Linux, QEMU on macOS). To force a specific backend:

```bash theme={null}
export SMOLVM_BACKEND=auto   # or firecracker, or auto (the default)
```

## Optional extras

Install extras for agent framework examples or the web dashboard:

```bash theme={null}
pip install "smolvm[examples]"   # pydantic-ai, openai-agents, langchain, playwright
pip install "smolvm[dashboard]"  # fastapi, uvicorn, websockets
pip install "smolvm[all]"        # everything above
```

<Tip>
  If you only need SmolVM as a sandbox, the base `pip install smolvm` is all you need.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Linux: KVM not available">
    If `/dev/kvm` doesn't exist, enable virtualization:

    ```bash theme={null}
    sudo modprobe kvm_intel   # Intel CPUs
    sudo modprobe kvm_amd     # AMD CPUs
    ls -l /dev/kvm
    ```

    For cloud VMs, enable nested virtualization in your hypervisor settings.
  </Accordion>

  <Accordion title="Linux: Permission denied on /dev/kvm">
    Add your user to the `kvm` group and activate it:

    ```bash theme={null}
    sudo usermod -aG kvm $USER
    newgrp kvm
    ```
  </Accordion>

  <Accordion title="macOS: qemu-system not found">
    Ensure Homebrew's bin directory is in your `PATH`:

    ```bash theme={null}
    export PATH="/opt/homebrew/bin:$PATH"   # Apple Silicon
    export PATH="/usr/local/bin:$PATH"      # Intel
    ```
  </Accordion>
</AccordionGroup>

For golden-AMI builds, two-stage deploys, pinning the Firecracker version, and other non-default install paths, see the [upstream installation guide](https://github.com/CelestoAI/SmolVM/blob/main/docs/installation.md).

## Uninstall

```bash theme={null}
pip uninstall smolvm
rm -rf ~/.local/state/smolvm ~/.smolvm
```

<Warning>
  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.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/smolvm/quickstart">
    Run your first sandbox in minutes
  </Card>

  <Card title="Basic usage" icon="gear" href="/smolvm/guides/basic-usage">
    Learn about VM configuration options
  </Card>

  <Card title="Custom images" icon="box" href="/smolvm/guides/custom-images">
    Build your own VM images with custom tools
  </Card>

  <Card title="API reference" icon="book" href="/smolvm/api/smolvm">
    Explore the complete API
  </Card>
</CardGroup>