Build From Source

We recommend developing EnvPool on Ubuntu 24.04. Release wheels are built for Python 3.12-3.14 in manylinux_2_28_x86_64 and manylinux_2_28_aarch64 environments for Linux, on macos-14 for macOS, and on windows-2022 for Windows.

Runtime data ships in the three envpool-assets* packages from the 0.4.x compatibility line, including the updated MyoSuite and Playground models. The main wheel requires this asset version line; older EnvPool releases remain on 0.3.x so they do not automatically receive the new models. The base envpool-assets package must be at least 0.4.1 for the DMC Composer locomotion and Soccer assets; the other two packages still accept 0.4.0.

We use bazel to build EnvPool. Comparing with pip, using Bazel to build python package with C++ .so files has some advantages:

  • Bazel allows us to build from source code, but no need to directly includes the code in our repo;

  • no need to write complex CMake files, especially with multiple third-party dependencies;

  • using Bazel for CI test pipeline can only run the test with modified part, so that it can save a lot of time.

Install Bazelisk

Bazelisk is a version controller for Bazel. You can install it via npm

sudo apt install -y npm
npm install -g @bazel/bazelisk

or golang with version >= 1.16:

sudo apt install -y golang-go
export PATH=$HOME/go/bin:$PATH
go install github.com/bazelbuild/bazelisk@latest
ln -sf $HOME/go/bin/bazelisk $HOME/go/bin/bazel

Note

For users in mainland China, please do the following step to install go and bazel:

  1. Install golang >= 1.16 from other sites, e.g., https://studygolang.com/dl

  2. Change go proxy: go env -w GOPROXY=https://goproxy.cn

  3. Install bazel from https://mirrors.huaweicloud.com/bazel/

wget https://studygolang.com/dl/golang/go1.18.1.linux-amd64.tar.gz
# then follow the instructions on golang official website
go env -w GOPROXY=https://goproxy.cn

wget https://mirrors.huaweicloud.com/bazel/9.2.0/bazel-9.2.0-linux-x86_64
chmod +x bazel-9.2.0-linux-x86_64
mkdir -p $HOME/go/bin
mv bazel-9.2.0-linux-x86_64 $HOME/go/bin/bazel

export PATH=$PATH:$HOME/go/bin  # or write to .bashrc / .zshrc

# check if successfully installed
bazel

See Issue #87.

Install Other Dependencies

EnvPool source builds share a few common requirements across platforms:

  • Python >= 3.12

  • Java 17

  • Go >= 1.22 plus bazelisk / bazel

  • SWIG

  • Qt 6 (Qt 5 is also supported for source builds)

The default build and test shortcuts in this repo use Bazel 9.2.0 via bazelisk. Bazel dependencies are configured as modules in MODULE.bazel.

Linux (Ubuntu 24.04)

EnvPool currently builds with the system GCC/G++ toolchain on Ubuntu 24.04. To install the required development packages:

sudo apt install -y build-essential openjdk-17-jdk python3-dev \
  python3-pip python-is-python3 golang-go cmake ninja-build swig qt6-base-dev \
  libegl1-mesa-dev libopengl-dev libx11-dev libxext-dev

macOS

macOS 13 or newer is required by Qt 6.11. Install the Xcode Command Line Tools first, then install the user-space dependencies with Homebrew:

xcode-select --install
brew install go openjdk@17 cmake ninja swig qtbase
sudo ln -sf "$(brew --prefix cmake)/bin/cmake" /usr/local/bin/cmake
sudo ln -sf "$(brew --prefix ninja)/bin/ninja" /usr/local/bin/ninja

export PATH="$(brew --prefix openjdk@17)/bin:$PATH"
export BAZEL_RULES_QT_DIR="$(brew --prefix qtbase)"

Windows

Install the following before building from source:

  • Visual Studio 2022 (or Build Tools 2022) with the Desktop development with C++ workload

  • Git for Windows

  • Java 17

  • Go 1.22+

  • Qt 6.11.1 with the msvc2022_64 toolchain

Then install the remaining command-line dependencies and export the Bazel / Qt environment variables:

choco install -y cmake make ninja strawberryperl swig
$env:BAZEL_SH = "C:/Program Files/Git/usr/bin/bash.exe"
$env:QT_ROOT_DIR = "C:/Qt/6.11.1/msvc2022_64"
$env:BAZEL_RULES_QT_DIR = $env:QT_ROOT_DIR
$env:PATH = "$env:QT_ROOT_DIR\\bin;$env:PATH"

If you want to reproduce the Windows MuJoCo render validation from CI, install Mesa software OpenGL as well and export:

$env:ENVPOOL_DLL_DIR = "C:/mesa"
$env:GALLIUM_DRIVER = "llvmpipe"
$env:MESA_GL_VERSION_OVERRIDE = "4.5COMPAT"

EnvPool loads libglapi.dll, libgallium_wgl.dll, and opengl32.dll from ENVPOOL_DLL_DIR before the Windows MuJoCo render tests and before the GLFW-backed render path.

Graphics runtime in wheels

Linux manylinux_2_28 wheels bundle Qt 6.11.1 QtCore/QtGui through auditwheel. third_party/qt/build_release.sh builds the shared libraries from the pinned official sources inside each architecture’s AlmaLinux 8 image, preserving the glibc 2.28 baseline. Procgen only needs raster drawing and PNG decoding, so this build omits ICU, window-system backends, fonts, and unused Qt modules. End users do not need a separate Qt installation. Release tests run with the build SDK moved out of its install path and check that Qt is loaded from the wheel.

The bundled Qt libraries use LGPLv3. Their license texts, component notices, source URL, checksum, and build configuration are included under the wheel’s .dist-info/licenses/qt6 directory. For a local manylinux release build, run:

python3 -m pip install --upgrade cmake ninja
bash third_party/qt/build_release.sh /opt/envpool-qt6
export BAZEL_RULES_QT_DIR=/opt/envpool-qt6
export WHEEL_LICENSE_DIR=/opt/envpool-qt6/licenses/qt6
make pypi-wheel

Windows release wheels currently bundle the Qt runtime DLLs required by Procgen (Qt6Core.dll and Qt6Gui.dll) directly next to procgen_envpool.pyd. End users installing the wheel do not need a separate Qt installation at runtime on Windows. The Qt license texts, SDK component notices, and build configuration are also included under .dist-info/licenses/qt6. Release builds collect these with third_party/qt/build_release.sh --licenses-only "$QT_ROOT_DIR".

macOS wheels do not bundle Qt frameworks. Install Homebrew Qt 6 with brew install qtbase before importing EnvPool; the frameworks are required at runtime as well as at build time. Qt 6.11 requires macOS 13 or newer.

Linux MuJoCo wheels also use system EGL and OpenGL libraries (libEGL.so.1, libOpenGL.so.0, and libGLdispatch.so.0). Keeping these on the system GL dispatch stack avoids auditwheel renaming EGL libraries that MuJoCo’s GL loader needs to recognize. For Mesa on Ubuntu, install libegl1 libopengl0 libgl1-mesa-dri.

Source builds prefer a local Qt 6 installation; Qt 5 remains supported when Qt 6 is unavailable. Set BAZEL_RULES_QT_DIR to select a specific install. Source builds can use system Qt packages or a custom installation prefix.

Install CUDA to enable XLA: see https://developer.nvidia.com/cuda-downloads

Install other dependencies: see Dockerfile.

Build Wheel

To build a release version, type:

cp third_party/pip_requirements/requirements-release.txt third_party/pip_requirements/requirements.txt
bazel run --config=release //:setup -- bdist_wheel

This creates a wheel under bazel-bin/setup.runfiles/_main/dist.

Note

For users in mainland China:

  • If you find pip install is quite slow to fetch 3rd-party libraries, configure pip.default(index_url = ...) in MODULE.bazel to switch the package source.

  • If you find bazel build is quite slow to fetch 3rd-party libraries, please refer https://docs.bazel.build/versions/main/external.html#using-proxies

    export HTTP_PROXY=http://...
export HTTPS_PROXY=http://...
# then run the command to build

See Issue #87.

Use Shortcut

We provide several shortcuts to make things easier.

# This will install bazelisk via golang, need sudo
make bazel-install

# This will verbose all compile commands to help debug
make bazel-debug

# This will build python wheel (.whl) file under `dist/` folder
make bazel-build

# This will automatically run the tests
make bazel-test

# On Windows, export ENVPOOL_DLL_DIR/GALLIUM_DRIVER/
# MESA_GL_VERSION_OVERRIDE first if you want MuJoCo render to use Mesa.

# This will generate a merged Python + C/C++ LCOV report
make bazel-coverage

# Normalize LCOV source paths before rendering HTML with genhtml
python3 scripts/coverage_summary.py \
  --lcov bazel-out/_coverage/_coverage_report.dat \
  --genhtml-lcov-file coverage/lcov.genhtml.info \
  --repo-root "$PWD"

# This will build a wheel for release
make bazel-release

# This will install the built wheel and run the release smoke, including
# one render() call after reset() for the wheel smoke envs.
make release-test

Use Docker to Create Develop Environment

We also provide dockerfile for building such a container. To create a docker develop environment, run

make docker-dev

The code is under /app, and you can communicate with the host machine file system via /host.