Import upstream snapshot c19f713c415a699a79d71cd96aa13c3104a05047

Upstream: https://github.com/michaelgillett/mjlab Upstream-Commit: c19f713c415a699a79d71cd96aa13c3104a05047 Upstream-Branch: main
2026-08-28 15:42:17 +08:00
commit 32a241c28f
513 changed files with 120771 additions and 0 deletions
@@ -0,0 +1,233 @@
+.. _installation:
+
+Installation Guide
+==================
+
+This guide presents different installation paths so you can
+choose the one that best fits your use case.
+
+.. contents::
+   :local:
+   :depth: 1
+
+.. note::
+
+    **System Requirements**
+
+    - **Training**: Linux + NVIDIA GPU (CUDA 12.4+ recommended)
+    - **Evaluation**: Linux, macOS, or Windows (WSL)
+    - **Python**: 3.10 or higher
+
+    See :ref:`faq` for more details on what is exactly supported.
+
+
+How to choose an installation method?
+-------------------------------------
+
+Select the card that best matches how you plan to use ``mjlab``.
+
+.. grid:: 2
+   :gutter: 2
+
+   .. grid-item-card:: Method 1 - Use mjlab as a dependency (uv)
+      :link: install-uv-dependency
+      :link-type: ref
+
+      You are **using mjlab as a dependency** in your own project managed by ``uv``. **(Recommended for most users)**
+
+   .. grid-item-card:: Method 2 - Develop / contribute (uv)
+      :link: install-uv-develop
+      :link-type: ref
+
+      You are **trying mjlab** or **contributing to mjlab itself** directly from inside the mjlab repository, with ``uv`` managing the environment.
+
+   .. grid-item-card:: Method 3 - Classic pip / venv / conda
+      :link: install-pip
+      :link-type: ref
+
+      You are using **classic tools** (``pip`` / ``venv`` / ``conda``) and **do not use uv**.
+
+   .. grid-item-card:: Method 4 - Docker / clusters
+      :link: install-docker
+      :link-type: ref
+
+      You are **running in containers or on clusters** and prefer a **Docker-based** setup.
+
+
+.. _install-uv-dependency:
+
+Method 1 - Use mjlab as a dependency (uv)
+-----------------------------------------
+
+This is our recommended way to use ``mjlab``. You have
+your own project and want to use ``mjlab`` as a dependency
+using ``uv``.
+
+1. Install uv
+^^^^^^^^^^^^^
+
+If you do not have ``uv`` installed, run:
+
+.. code-block:: bash
+
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+
+2. Initialize your project
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Initialize a managed Python project:
+
+.. code-block:: bash
+
+   # Create a new package-based project
+   uv init --package my_mjlab_project
+   cd my_mjlab_project
+
+3. Add mjlab dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are different options to add ``mjlab`` as a dependency.
+We recommend using the latest stable version from PyPI. If you need
+the latest features, use the direct GitHub installation. Finally, if you
+need to use a feature you have developed locally, use the local editable
+install. These options are interchangeable: you can switch at any time.
+
+.. tab-set::
+
+   .. tab-item:: PyPI
+
+      Once in your project, install the latest snapshot from PyPI:
+
+      .. code:: bash
+
+         uv add mjlab
+
+   .. tab-item:: Source
+
+      Once in your project, install directly from GitHub without cloning:
+
+      .. code:: bash
+
+         uv add "mjlab @ git+https://github.com/mujocolab/mjlab"
+
+   .. tab-item:: Local
+
+      Clone the repository:
+
+      .. code:: bash
+
+         git clone https://github.com/mujocolab/mjlab.git
+
+      Once in your project, add it as an editable dependency:
+
+      .. code:: bash
+
+         uv add --editable /path/to/cloned/mjlab
+
+.. tip::
+
+   For a complete example of how to structure a project that integrates a custom robot
+   with an existing ``mjlab`` task, check out the
+   `ANYmal C Velocity Tracking <https://github.com/mujocolab/anymal_c_velocity>`_ repository.
+
+Verification
+^^^^^^^^^^^^
+
+After installation, verify that ``mjlab`` is working by running the demo:
+
+.. code-block:: bash
+
+   uv run demo
+
+
+.. _install-uv-develop:
+
+Method 2 - Develop / contribute (uv)
+------------------------------------
+
+This method is for developing ``mjlab`` itself or contributing to the project.
+
+.. code:: bash
+
+   git clone https://github.com/mujocolab/mjlab.git && cd mjlab
+   uv sync
+
+Verification
+^^^^^^^^^^^^
+
+After installation, verify that ``mjlab`` is working by running the demo:
+
+.. code-block:: bash
+
+   uv run demo
+
+
+.. _install-pip:
+
+Method 3 - Classic pip / venv / conda
+-------------------------------------
+
+Activate your virtual environment (``venv``, ``conda``, etc.), then install:
+
+.. code:: bash
+
+   pip install mjlab
+
+
+Verification
+^^^^^^^^^^^^
+
+After installation, verify that ``mjlab`` is working by running the demo:
+
+.. code-block:: bash
+
+   demo
+
+
+.. _install-docker:
+
+Method 4 - Docker / clusters
+----------------------------
+
+Prerequisites:
+
+- Install Docker: `Docker installation guide <https://docs.docker.com/engine/install/>`_.
+- Install an appropriate NVIDIA driver for your system and the
+  `NVIDIA Container Toolkit <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html>`_.
+
+  - Be sure to register the container runtime with Docker and restart,
+    as described in the Docker configuration section of the NVIDIA
+    install guide.
+
+.. tab-set::
+
+   .. tab-item:: Pre-built image (recommended)
+
+      Pull and run the latest image from the GitHub Container Registry:
+
+      .. code-block:: bash
+
+         docker run --rm --runtime=nvidia --gpus all \
+           ghcr.io/mujocolab/mjlab uv run demo
+
+      The image is rebuilt on every push to ``main``.
+
+   .. tab-item:: Local build
+
+      Build from source and run:
+
+      .. code-block:: bash
+
+         ./scripts/run_docker.sh uv run demo
+
+
+Having some troubles?
+---------------------
+
+1. **Check the FAQ**
+
+    Consult the mjlab :ref:`faq` for answers to common installation and runtime issues
+
+2. **Still stuck?**
+
+    Open an issue on GitHub: https://github.com/mujocolab/mjlab/issues