Installation

FlyGym can be installed as a regular Python package via PyPI or as a developer installation from the source code. In addition, we provide a Docker image with FlyGym and its dependencies pre-installed. Below, we provide instructions for each of these methods.

Installation via PyPI

The easiest way to install FlyGym is via PyPI. Before you start, you might want to create a Python virtual environment with virtualenv or Conda. For example, with Conda:

conda create -n flygym python=3.12    # flygym is tested on Python 3.9-3.12
conda activate flygym    # run this every time you use the environment

Then, to install the FlyGym package:

pip install "flygym"

Important

Headless machines: If you want to run FlyGym on a machine without a display (e.g. a server or a node on a cluster), please check the special instructions at the bottom of this page.

Note

(Optional) Additional dependencies for provided tutorials and examples: A number of additional dependencies are required to run the provided tutorials and examples. To install these dependencies, you can run the following command:

pip install "flygym[examples]"

The tutorial and example on interfacing FlyGym with the connectome-constrained vision model from Lappalainen et al. (2024) further requires the FlyVision package, which is not published on the Python Package Index (PyPI). As a result, the command above does not install FlyVision. Instead, you must either install it manually following its installation instructions, or install it with pip from our fork on GitHub:

pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"

Note

(Optional) Additional tools for developers: Developers of FlyGym use a number of other tools for automated documentation generation, testing, and code linting. These tools are not required to use FlyGym as it is, but can be useful if you wish to modify the code or contribute to the project. To install these tools, you can run:

pip install "flygym[dev]"

Note, however, that pip installation does not easily allow the user to modify the source code. If you want to modify the source code, please follow the instructions below for developer installation.

Developer installation

First, clone this repository:

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

Change into the cloned directory:

cd flygym

If you want to install code from a specific branch, you can checkout to the branch of your choice:

git checkout <branch_name>

You might want to create a Python virtual environment with virtualenv or Conda. For example, with Conda:

conda create -n flygym python=3.12    # flygym is tested on Python 3.9-3.12
conda activate flygym    # run this every time you use the environment

Next, install the FlyGym package:

pip install -e .

Note that the -e causes the package to be installed in editable mode. This means that you can modify the source code and the changes will be reflected in the installed package. This is useful if you want to modify modify the FlyGym package itself in your work — in which case we ask you to consider sharing your developments with us via a pull request (PR) to make it available to the community. Please refer to the contribution guide for more information.

Developers should also install the dev dependencies for testing and documentation:

pip install -e ."[dev]"

Note

The quotation marks around the package name are important if you are using zsh (the default shell on Macs). Without them, pip will not receive flygym[dev] as a single string.

Finally, if you want to install the additional dependencies required to run the provided examples (eg. NetworkX, PyTorch, etc.), run:

pip install -e ."[examples]"

Cross-platform compatibility

FlyGym supports Linux, macOS, and Windows, although rendering on headless Mac and Windows servers (i.e., without displays) is not tested. To render on a headless Linux server, follow the special instructions at the bottom of this page.

FlyGym is automatically tested in the following setups:

  • Linux: latest version of Ubuntu, with Python 3.9, 3.10, 3.11, and 3.12.

  • macOS: latest version of macOS (Apple silicon) and macOS 13 Ventura (pre Apple silicon), wih Python 3.12, without rendering.

  • Windows: latest version of Windows, with Python 3.12, without rendering.

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 change the renderer to EGL (see this link 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

Docker image

“Containerization” is a way of virtualization that aims to bundle an application and its dependencies into a single portable, executable unit called a container. Docker is a popular platform for developing, shipping, and running containers, making it easier to manage and deploy applications in a consistent manner.

Instead of installing FlyGym on your machine directly, you can also install Docker on your machine and run FlyGym through Docker. This might be particularly helpful if you are using container-as-a-service (CaaS) systems such as Kubernetes to train or deploy models at scale. We provide a Docker image with FlyGym and its dependencies pre-installed and publish it to Docker Hub. This image is defined by the Dockerfile at the root level of the directory.

For more information about how to interact with Docker, please refer to the official Docker guides. Note that you need to install NVIDIA Container Toolkit if you would like to use an NVIDIA GPU from the container.

Troubleshooting

  • AttributeError: module 'pkgutil' has no attribute 'ImpImporter'. Did you mean: 'zipimporter'? during opencv-python installation:

    • This appears to be an issue with opencv-python on certain Mac systems with Python 3.12. Please refer to this GitHub issue. Temporary fixes (from simple to complex) include:

      • Use Python 3.11 instead.

      • Uninstall opencv-python, clone opencv-python from GitHub, remove the line "setuptools==59.2.0", in its pyproject.toml, install an up-to-date version of setuptools (e.g., 70.0.0), and install opencv-python locally from the cloned directory. Then, continue with the FlyGym installation.

      • Use Docker to run FlyGym (see above).