Skip to main content
Choose your installation method based on your needs. For most users, pip or uv installation is recommended. Install from source if you’re developing rfx itself or need the latest unreleased features.

​
Prerequisites

Python 3.13+

Required for all installation methods

Rust toolchain

Required for source installation only

uv (optional)

Faster package management

​
System requirements

  • Python: 3.13 or 3.14
  • Operating System: Linux, macOS, or Windows (Linux recommended for hardware)
  • Rust: 1.70+ (source installation only)

​
Quick install

For most users, install the published package from PyPI: 
uv pip install rfx-sdk
This installs:
  • Core Python package (rfx)
  • Rust extension for real-time control
  • Essential dependencies (tinygrad, numpy, PyYAML)
  • CLI tool (rfx command)
Why uv? uv is a fast Python package installer written in Rust. It’s significantly faster than pip and handles dependency resolution more reliably.Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh

​
Optional dependencies

rfx has several optional feature groups. Install only what you need:

​
Simulation backends

uv pip install "rfx-sdk[sim-genesis]"
Simulation dependencies:
  • sim-genesis: torch, genesis-world ≥0.4.0 (GPU recommended)
  • sim-mjx: torch, mujoco ≥3.0, jax[cuda13], warp-lang
  • sim-mock: torch only (runs on CPU)

​
Teleoperation and data collection

uv pip install "rfx-sdk[teleop]"
Includes:
  • opencv-python ≥4.8 (camera capture)
  • torch ≥2.2
  • mcap ≥1.1.0 (logging)

​
LeRobot integration

uv pip install "rfx-sdk[collection]"
Enables:
  • Direct export to LeRobot datasets
  • HuggingFace Hub push/pull
  • Compatible with lerobot package

​
LLM agent integration

uv pip install "rfx-sdk[agent]"
Provides:
  • anthropic ≥0.25.0 (Claude)
  • openai ≥1.0.0 (GPT)

​
Development tools

uv pip install "rfx-sdk[dev]"
Includes:
  • pytest ≥7.0, pytest-asyncio
  • ruff ≥0.1 (linting and formatting)
  • mypy ≥1.0 (type checking)
  • pre-commit ≥3.6

​
All optional features

Install everything: 
uv pip install "rfx-sdk[all]"
The [all] extra includes GPU libraries (JAX, CUDA) which may require specific driver versions. Install only the features you need for smaller, faster installs.

​
Install from source

For development or bleeding-edge features:
1
Clone the repository
2
git clone https://github.com/quantbagel/rfx.git
cd rfx
3
Run the setup script
4
The setup script handles everything automatically:
5
bash scripts/setup-from-source.sh
6
This script:
7
  • Creates a virtual environment at .venv/
  • Installs development requirements from requirements-dev.txt
  • Installs rfx in editable mode (pip install -e)
  • Fetches Rust dependencies
  • Probes available backends (CUDA, Metal)
  • Configures git hooks for quality checks
    • 8
    Activate the environment
    9
    source .venv/bin/activate
    10
    Verify the installation
    11
    rfx doctor

    ​
    Custom virtual environment path

    Override the default .venv location: 
    RFX_VENV_PATH=/path/to/venv bash scripts/setup-from-source.sh

    ​
    Manual source installation

    If you prefer to install manually: 
    # Create and activate virtualenv
uv venv .venv
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements-dev.txt

# Install rfx in editable mode
uv pip install -e .

# Fetch Rust dependencies
cargo fetch

    ​
    Run without installation

    Use uv run to execute rfx commands without installing: 
    uv run rfx deploy runs/my-policy --robot so101
uv run rfx record --robot so101 --repo-id demos --episodes 10
    This is useful for:
    • Quick testing without environment setup
    • Running examples from the repo
    • CI/CD pipelines

    ​
    Verify installation

    Check that everything is working: 
    rfx doctor
    Expected output: 
    [rfx] doctor

  Version
    rfx-sdk          0.2.0
    Python           3.13.x
    Platform         Linux-x.x.x

  Required tools
    python3          ok  /usr/bin/python3
    cargo            ok  /usr/bin/cargo
    uv               ok  /usr/bin/uv

  Rust extension
    rfx._rfx         ok  v0.2.0

  Core Python packages
    tinygrad         ok  0.9.0
    NumPy            ok  1.26.0
    PyYAML           ok  6.0

  Optional packages
    PyTorch          ok  2.2.0
    LeRobot          not available
    OpenCV           ok  4.8.0
    ...

  Simulation backends
    MockRobot        ok
    Genesis (GPU)    not available  requires genesis
    MJX (JAX)        not available  requires mujoco

[rfx] All good. Ready to go.
    not available for optional packages is normal. Only install what you need.

    ​
    Troubleshooting

    ​
    Rust extension not found

    If rfx doctor reports rfx._rfx missing: 
    # Rebuild the Rust extension
maturin develop

    ​
    Backend probe fails

    If GPU backends (CUDA, Metal) don’t appear:
    1. Check that you have appropriate drivers installed
    2. Install tinygrad runtime support: 
      pip install tinygrad[cuda]  # for NVIDIA
pip install tinygrad[metal]  # for Apple Silicon
    3. Verify with: 
      from rfxJIT.runtime import available_backends
print(available_backends())

    ​
    Import errors

    If you see ModuleNotFoundError: No module named 'rfx':
    1. Ensure you activated the virtual environment
    2. Reinstall in editable mode: uv pip install -e .
    3. Check that you’re in the repo root directory

    ​
    Serial port permissions (Linux)

    For hardware access, add your user to the dialout group: 
    sudo usermod -a -G dialout $USER
# Log out and back in for changes to take effect

    ​
    Development setup

    For contributors or those modifying rfx source:

    ​
    Enable git hooks

    Setup pre-commit hooks for quality gates: 
    ./scripts/setup-git-hooks.sh
    This configures:
    • pre-commit: Rust format check + Ruff on staged files
    • pre-push: Full test suite (Rust + Python)
    To block accidental pushes to main: 
    RFX_BLOCK_MAIN_PUSH=1 ./scripts/setup-git-hooks.sh

    ​
    Use Moon task runner

    rfx uses Moon for monorepo task orchestration: 
    # Run all checks
moon run :format
moon run :lint
moon run :typecheck
moon run :test
moon run :build
    See .moon/workspace.yml for configuration.

    ​
    Manual quality checks

    Without Moon, use the Python checks script: 
    scripts/python-checks.sh lint
scripts/python-checks.sh typecheck
scripts/python-checks.sh test
scripts/python-checks.sh ci  # all checks
    For full mypy package check: 
    RFX_TYPECHECK_FULL=1 scripts/python-checks.sh typecheck-full

    ​
    Next steps

    Quickstart

    Get your first policy running in minutes

    SO-101 Setup

    Configure your SO-101 robotic arm

    Simulation

    Set up simulation backends

    Python SDK

    Explore the API reference

    Build docs developers (and LLMs) love

    Get started for freeTalk to us