Installation

Using pipUsing uv (for development)Using DockerOnline using Google Colab

Virtual Environments

We recommend that you create a virtual environment (using venv, Conda, uv, Poetry, etc.).

FlyGym is published on the Python Package Index (PyPI). You can use FlyGym using pip directly. If you only care about the basic functionalities:

pip install flygym

Add the warp optional dependency if you want to use the flygym.warp GPU-accelerated backend:

pip install flygym[warp]

Add the examples optional dependency if you want to follow the tutorials:

pip install flygym[examples]

Add the rl optional dependency for reinforcement-learning training (e.g. the muscle imitation tutorial), which installs Gymnasium, Stable-Baselines3, and TensorBoard:

pip install flygym[rl]

You can combine multiple optional dependencies in one command. For example:

pip install flygym[warp,examples,rl]

FlyGym uses uv for package management. Install uv following its official documentation.

Clone the FlyGym repository:

git clone git@github.com:NeLy-EPFL/flygym.git
cd flygym

Then install using uv. The following installs all optional dependencies, but you can

• remove --extra warp if you don't care for GPU acceleration, or if you don't have a NVIDIA GPU (e.g., you're on a Mac),
• remove --extra dev if you don't care for development tools (e.g., unit testing, automatic doc generation), or
• remove --extra examples if you don't care for running the tutorials.

uv sync --extra warp --extra dev --extra examples

Note

Developers should also install the nbstripout filter, which removes bulky Jupyter Notebook outputs upon git add (without touching the actual files—the outputs are only removed in the version-controlled files). Note that this does not integrate well with IDEs, so you should run git add <files> in command line instead of using, for example, the GUI in VS Code.

source .venv/bin/activate
nbstripout --install --attributes .gitattributes

Profiling FlyGym simulations

For instructions on CPU/GPU performance profiling (including the nsys prerequisite), see the Performance profiling guide.

FlyGym is published as a Docker image on Docker Hub. The image comes with all optional dependencies pre-installed and EGL rendering pre-configured, making it suitable for headless servers.

Pull the latest image:

docker pull nelyepfl/flygym

Or pull a specific version (e.g., v2.0.2):

docker pull nelyepfl/flygym:v2.0.2

Start an interactive shell inside the container:

docker run -it nelyepfl/flygym

To share files between your host machine and the container, mount a local directory:

docker run -it -v /path/to/your/work:/root/work nelyepfl/flygym

The FlyGym source code is located at /root/flygym inside the container. The virtual environment is managed by uv; activate it with:

source /root/flygym/.venv/bin/activate

You can run the tutorials in Google Colab without installing anything locally. Every tutorial notebook (excluding text-only ones) has an "Open in Colab" badge at the top:

Colab is slow

Execution on Colab can be up to ~50× slower than on a local machine or dedicated GPU, depending on the resources Colab makes available at the time. Use Colab only for testing and following along with the tutorials—not for production runs or benchmarking.

Click the badge to open the notebook in Colab, then run the first code cell (titled Google Colab setup). It installs FlyGym from GitHub (matching the version of the notebook) and configures headless (EGL) rendering for you:

import os
import sys

if "google.colab" in sys.modules:
    os.environ["MUJOCO_GL"] = "egl"
    os.environ["PYOPENGL_PLATFORM"] = "egl"
    %pip install -q tqdm "flygym @ git+https://github.com/NeLy-EPFL/flygym.git@v2.1.0"

Note

On Colab we install plain flygym (rather than flygym[examples]) because the examples extra would upgrade ipython, ipykernel, and pandas over the versions Colab ships, triggering dependency-conflict warnings. The tutorials only need tqdm on top of base FlyGym, so we install that explicitly.

After the setup cell finishes, run the rest of the notebook as usual. FlyGym downloads the fly meshes from S3 on first use, so no large files need to be uploaded.

GPU-accelerated tutorial

The GPU-accelerated simulation tutorial uses the flygym.warp backend, which requires a GPU. Before running it, switch Colab to a GPU runtime via Runtime > Change runtime type > T4 GPU. Its setup cell installs the warp extra automatically.

On a GPU runtime, pip may warn that Colab's preinstalled cudf/cuml (RAPIDS) require numba<0.62 while FlyGym installs a newer numba. This warning is harmless: the tutorial uses MuJoCo Warp, not RAPIDS, so the upgraded numba does not affect it.

Special notes for rendering on machines without a display

If you are using a machine without a display (e.g. a server), you will need to switch the renderer to EGL (see this page for details). This requires setting the following environment variables before running FlyGym:

export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl

If you want to change this setting by default, you can add the two lines above to the end of your .bashrc file.

If you are using a Conda environment, you can change the environment variables as follows (replacing my-env-name accordingly), and then re-activate the environment:

conda activate my-env-name
conda env config vars set MUJOCO_GL=egl PYOPENGL_PLATFORM=egl

You might need to install EGL-related dependencies on your machine. For example, on some Ubuntu/Debian systems, you might need to install the following:

apt-get install libegl1-mesa-dev