Installation

Requirements

Python 3.12 or newer. The core install needs only NumPy, SciPy and Matplotlib.

From PyPI

pip install flybots

Optional extras:

pip install "flybots[gym]"     # Gymnasium integration for external RL libraries
pip install "flybots[video]"   # MP4 export via a bundled ffmpeg
pip install "flybots[gym,video]"

Neither extra is needed to train a policy — the built-in trainer is pure NumPy. gym only matters if you want to drive the environments with Stable-Baselines3, CleanRL or similar.

Upgrading from 1.x

The import package was renamed in 2.0.0. It was uav_sim; it is now flybots, matching the distribution and the command:

from uav_sim.vehicles.multirotor import Quadrotor   # 1.x
from flybots.vehicles.multirotor import Quadrotor   # 2.0

The Gymnasium environment ids moved with it: uav_sim/Hover-v0 is now flybots/Hover-v0. There is no compatibility shim — import uav_sim fails outright rather than working with a warning, so a missed import surfaces at once instead of partway through a training run.

The old uav-sim command survives one more release. It prints a deprecation notice on stderr and forwards to flybots.

From source

The project uses uv:

git clone https://github.com/guilyx/flybots.git
cd flybots
uv sync --all-groups

uv sync reads .python-version, fetches the right interpreter, and installs the package in editable mode with the dev tooling.

Plain pip works too:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[gym,video]"
pip install pytest ruff pre-commit

Git LFS

The repository stores its preview GIFs in Git LFS. If you only want the code, GIT_LFS_SKIP_SMUDGE=1 git clone ... skips roughly 150 MB of media and clones in a few seconds instead of a few minutes. You get pointer files in place of the GIFs; git lfs pull fetches them later if you need them.

Verify

flybots doctor

This prints the interpreter and dependency versions, counts the simulation catalogue, and then flies each airframe briefly to confirm the physics behaves:

Physics self-check
──────────────────
  ok        fixed-wing holds trim    0.000 m drift
  ok        quadrotor hovers         0.000 m drift
  ok        VTOL hovers              0.000 m drift

A FAIL here means something is genuinely wrong with the install rather than with your code — please open an issue with the full output.

Run the tests

uv run pytest              # full suite
uv run pytest -q -x        # stop at the first failure
uv run pytest tests/test_fixed_wing_aero.py -v

The suite runs real simulations rather than mocks, so it takes a few minutes. That is the point — the tests assert on flight behaviour, not on array shapes.

Development setup

pre-commit install
pre-commit install --hook-type commit-msg
pre-commit run --all-files

Ruff handles formatting and linting; commitizen enforces Conventional Commits on the commit message. See CONTRIBUTING.md.

Building the docs

cd docs
npm ci
npm run dev      # http://localhost:5173
npm run build

Headless environments

Every simulation sets the Matplotlib Agg backend explicitly, so rendering works over SSH and in CI with no display. Nothing opens a window.