feat: support Python 3.11 for simulation and training

.github/workflows/tests.yml

@@ -18,13 +18,14 @@ concurrency:
 
 jobs:
   pytest:
-    name: pytest (${{ matrix.suite }})
+    name: pytest (${{ matrix.suite }}, Python ${{ matrix.python }})
     runs-on: ubuntu-latest
     timeout-minutes: 45
     strategy:
       fail-fast: false
       matrix:
-        include: ${{ fromJSON((github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && '[{"suite":"full","selection":""}]' || '[{"suite":"fast","selection":"not slow and not integration and not numba"},{"suite":"numba","selection":"not integration and (slow or numba)"}]') }}
+        python: ["3.10", "3.11"]
+        suite: ${{ fromJSON((github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && '["full"]' || '["fast","numba"]') }}
     steps:
       - name: Resolve numba cache dir
         run: |
@@ -39,10 +40,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.cache/motrixlab
-          key: numba-kernel-${{ runner.os }}-${{ matrix.suite }}-${{ github.sha }}
+          key: numba-kernel-${{ runner.os }}-py${{ matrix.python }}-${{ matrix.suite }}-${{ github.sha }}
           restore-keys: |
-            numba-kernel-${{ runner.os }}-${{ matrix.suite }}-
-            numba-kernel-${{ runner.os }}-
+            numba-kernel-${{ runner.os }}-py${{ matrix.python }}-${{ matrix.suite }}-
+            numba-kernel-${{ runner.os }}-py${{ matrix.python }}-
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -55,23 +56,37 @@ jobs:
           enable-cache: true
 
       - name: Set up Python
-        run: uv python install 3.10
+        run: uv python install '${{ matrix.python }}'
 
       - name: Install workspace and test dependencies
-        run: sh install.sh --all
+        run: |
+          if [ '${{ matrix.python }}' = '3.10' ]; then
+            sh install.sh --all --python 3.10
+          else
+            # Unitree/DDS remains outside Python 3.11 runtime support.
+            uv sync --frozen --python 3.11 --extra cuda --extra rslrl --extra skrl-jax --extra tbb --group test
+          fi
+          .venv/bin/python -c 'import sys; assert ".".join(map(str, sys.version_info[:2])) == "${{ matrix.python }}"'
 
       - name: Run tests
-        env:
-          PYTEST_SELECTION: ${{ matrix.selection }}
         run: |
+          selection=''
+          case '${{ matrix.suite }}' in
+            fast) selection='not slow and not integration and not numba' ;;
+            numba) selection='not integration and (slow or numba)' ;;
+          esac
+          set --
+          if [ '${{ matrix.python }}' = '3.11' ]; then
+            set -- --ignore=motrix_deploy_unitree
+          fi
           .venv/bin/python -m pytest -q --strict-markers --disable-warnings \
             --durations=20 --junitxml=test-results/${{ matrix.suite }}.xml \
-            -m "$PYTEST_SELECTION"
+            -m "$selection" "$@"
 
       - name: Upload test results
         if: always()
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
-          name: pytest-${{ matrix.suite }}
+          name: pytest-py${{ matrix.python }}-${{ matrix.suite }}
           path: test-results/
           if-no-files-found: warn

AGENTS.md

@@ -117,9 +117,11 @@ Python 方法，由 manager 运行时契约定义（`wiki/design/manager/runtime
 
 ## 开发环境
 
-项目使用 UV 管理依赖，Python 版本要求 3.10.\*。可用的依赖组与 extras 见 `pyproject.toml`。
+项目使用 UV 管理依赖，默认 Python 3.10；不含 Unitree 硬件部署插件的仿真与训练也支持 Python 3.11。
+Unitree 硬件部署插件与包含该插件的 `--all` 安装仍仅支持 Python 3.10；Unitree 机器人模型的仿真与训练不受此限制。
+可用的依赖组与 extras 见 `pyproject.toml`。
 
-完整开发环境（全部 package、依赖组与 extras；`--gpu rocm` 切换 AMD wheel）：
+完整开发环境（Python 3.10，全部 package、依赖组与 extras；`--gpu rocm` 切换 AMD wheel）：
 
 ```bash
 sh install.sh --all
@@ -129,6 +131,8 @@ sh install.sh --all
 
 ```bash
 sh install.sh
+# 不含 Unitree 硬件部署插件的 Python 3.11 运行环境：
+sh install.sh --python 3.11
 ```
 
 避免裸 `uv run` / `uv sync`：`cuda`/`rocm` extras 声明为互斥，裸命令会解析到默认 fork（PyPI torch）

CONTRIBUTING.md

@@ -7,7 +7,8 @@ feature proposals, and Discussions for usage questions and design discussion.
 
 MotrixLab currently targets:
 
-- Python **3.10.x** (the workspace declares `==3.10.*`).
+- Python **3.10.x / 3.11.x**, with 3.10 as the default. Unitree hardware
+  deployment and `--all` require Python 3.10.
 - Linux x86_64 and Windows x86_64 for the documented CPU simulation and viewer
   workflows. The JAX training extra is Linux-only.
 - [uv](https://docs.astral.sh/uv/) for environments, dependency resolution,
@@ -23,16 +24,25 @@ cd MotrixLab
 git lfs pull
 ```
 
-Create the complete development environment from the repository root:
+Create the complete development environment (Python 3.10 only, including Unitree)
+from the repository root:
 
 ```bash
 sh install.sh --all       # --gpu rocm switches to the AMD wheels
 ```
 
 A runtime-only environment without the dev toolchain is available via `sh install.sh`: it
 auto-detects the GPU vendor (NVIDIA/AMD) for the torch wheels and `--rslrl`
-selects the RSLRL backend. On Windows, run `install.ps1` in PowerShell. Avoid bare
-`uv sync` / `uv run`: the `cuda`/`rocm` extras are declared conflicting, so a bare
+selects the RSLRL backend. To select Python 3.11 for a non-Unitree runtime:
+
+```bash
+sh install.sh --python 3.11
+```
+
+`--all` cannot be combined with Python 3.11. On Windows, run `install.ps1` in
+PowerShell.
+
+Avoid bare `uv sync` / `uv run`: the `cuda`/`rocm` extras are declared conflicting, so a bare
 command resolves the default fork (PyPI torch) and reinstalls the environment. Run
 commands from the activated environment (`source .venv/bin/activate`); the examples
 below assume it is active, or pass `--no-sync` to one-off `uv run` calls.

README.md

@@ -5,7 +5,7 @@
 # MotrixLab
 
 [![GitHub License](https://img.shields.io/github/license/Motphys/MotrixLab)](LICENSE)
-![Python Version](https://img.shields.io/badge/python-3.10-blue)
+![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11-blue)
 [![Release](https://img.shields.io/github/v/release/Motphys/MotrixLab?include_prereleases)](https://github.com/Motphys/MotrixLab/releases)
 [![Docs](https://img.shields.io/badge/docs-readthedocs-blue)](https://motrixlab.readthedocs.io)
 
@@ -56,7 +56,7 @@ _Microduck locomotion policies trained with MotrixLab, rendered in MotrixRender
 
 | Requirement | Notes |
 | --- | --- |
-| Python **3.10.x** | The workspace pins `==3.10.*` |
+| Python **3.10.x / 3.11.x** | Default: 3.10 |
 | [uv](https://docs.astral.sh/uv/) | Python project and dependency manager — [installation guide](https://docs.astral.sh/uv/getting-started/installation/) |
 | [Git LFS](https://git-lfs.com) | Robot meshes, motion data, and videos are tracked by LFS |
 | OS | Linux x86_64 or Windows x86_64; the JAX training backend is Linux-only |
@@ -72,12 +72,16 @@ git lfs pull
 
 ### 2. Install dependencies
 
-Linux:
+Linux (Python 3.10 by default):
 
 ```bash
 sh install.sh
+# Python 3.11 for simulation/training without the Unitree hardware plugin:
+sh install.sh --python 3.11
 ```
 
+Unitree hardware deployment and `--all` require Python 3.10; simulation/training with Unitree robot models can use Python 3.11.
+
 Windows (PowerShell):
 
 ```powershell

README.zh-CN.md

@@ -5,7 +5,7 @@
 # MotrixLab
 
 [![GitHub License](https://img.shields.io/github/license/Motphys/MotrixLab)](LICENSE)
-![Python Version](https://img.shields.io/badge/python-3.10-blue)
+![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11-blue)
 [![Release](https://img.shields.io/github/v/release/Motphys/MotrixLab?include_prereleases)](https://github.com/Motphys/MotrixLab/releases)
 [![Docs](https://img.shields.io/badge/docs-readthedocs-blue)](https://motrixlab.readthedocs.io)
 
@@ -56,7 +56,7 @@ _使用 MotrixLab 训练的 microduck 行走策略，由 MotrixRender 实时渲
 
 | 要求 | 说明 |
 | --- | --- |
-| Python **3.10.x** | workspace 锁定 `==3.10.*` |
+| Python **3.10.x / 3.11.x** | 默认 3.10 |
 | [uv](https://docs.astral.sh/uv/) | Python 项目与依赖管理工具 — [安装指南](https://docs.astral.sh/uv/getting-started/installation/) |
 | [Git LFS](https://git-lfs.com) | 机器人网格、运动数据与视频由 LFS 管理 |
 | 操作系统 | Linux x86_64 或 Windows x86_64；JAX 训练后端仅支持 Linux |
@@ -72,12 +72,16 @@ git lfs pull
 
 ### 2. 安装依赖
 
-Linux：
+Linux（默认 Python 3.10）：
 
 ```bash
 sh install.sh
+# 不含 Unitree 硬件部署插件的仿真与训练也可使用 Python 3.11：
+sh install.sh --python 3.11
 ```
 
+Unitree 硬件部署与 `--all` 仅支持 Python 3.10；Unitree 机器人模型的仿真与训练可使用 Python 3.11。
+
 Windows（PowerShell）：
 
 ```powershell

docs/source/en/user_guide/getting_started/installation.md

@@ -4,15 +4,18 @@ This document will guide you through the installation and configuration of Motri
 
 ## System Requirements
 
--   **Python Version**: {bdg-danger-line}`3.10.*`
+-   **Python Version**: {bdg-danger-line}`3.10.* / 3.11.*`
 
-    This project requires a specific Python version, other versions are not currently supported:
+    Python 3.10 is the default.
 
     | Python Version | Support Status |
     | :------------: | :------------: |
     |     ≤ 3.9      |       ❌       |
     |      3.10      |       ✅       |
-    |     ≥ 3.11     |       ❌       |
+    |      3.11      |       ✅       |
+    |     ≥ 3.12     |       ❌       |
+
+    Unitree hardware deployment and `--all` require Python 3.10; simulation/training with Unitree robot models can use Python 3.11.
 
 -   **Package Manager**: {bdg-danger-line}`UV`
 
@@ -46,7 +49,9 @@ cd MotrixLab
 Install the runtime environment from the repository root (on Windows, run `install.ps1` in PowerShell; if the execution policy blocks it, use `powershell -ExecutionPolicy Bypass -File install.ps1`):
 
 ```bash
-sh install.sh
+sh install.sh  # Python 3.10 by default
+# Python 3.11 runtime without the Unitree hardware deployment plugin:
+sh install.sh --python 3.11
 ```
 
 This auto-detects your GPU vendor (NVIDIA → CUDA, AMD → ROCm) and installs the runtime workspace packages, the matching PyTorch wheels, the required SKRL Torch provider, and the built-in FastSAC algorithm. On Linux, `install.sh` also installs Intel TBB by default for Numba parallel kernels, including with `--all` and either GPU profile. Other platforms do not enable TBB by default for runtime installation. Development tools, docs, RSL-RL, SKRL JAX, and other optional extras are not installed unless requested.
@@ -77,7 +82,8 @@ project (run tests, modify code, build the docs), install the full development e
 sh install.sh --all
 ```
 
-`--all` enables everything in one go: the dev toolchain, test dependencies, all training backends
+`--all` includes the Unitree hardware deployment plugin, so it requires Python 3.10 and cannot be combined with `--python 3.11`.
+It enables everything in one go: the dev toolchain, test dependencies, all training backends
 (SKRL Torch is required; `--skrl-jax` and `--rslrl` add the optional backends), and the docs tooling.
 On ROCm, CUDA-only extras such as SKRL JAX are skipped. You can also select individual additions,
 e.g. `sh install.sh --docs` adds only the docs toolchain.
@@ -90,7 +96,8 @@ workspace packages and supported development extras. Backend flags select or add
 
 | Option | Values | Description |
 | ------ | ------ | ----------- |
-| `--all` | — | Full development environment: everything below is enabled in one go (dev toolchain, test dependencies, all training backends, and docs tooling) |
+| `--python` | `3.10`<br>`3.11` | Select Python; defaults to `3.10`, with `3.11` for runtime installs without the Unitree hardware deployment plugin |
+| `--all` | — | Full development environment including Unitree; Python 3.10 only (dev toolchain, test dependencies, all training backends, and docs tooling) |
 | *(none)* | — | Runtime environment; the GPU vendor is auto-detected (NVIDIA → CUDA, AMD → ROCm; CUDA as fallback when detection is impossible) |
 | `--gpu` | `cuda`<br>`rocm` | Select the torch wheel flavor explicitly, overriding auto-detection |
 | `--skrl-torch` | — | Compatibility flag; SKRL Torch is already required by the root package |

docs/source/zh_CN/user_guide/getting_started/installation.md

@@ -4,15 +4,18 @@
 
 ## 系统要求
 
--   **Python 版本**：{bdg-danger-line}`3.10.*`
+-   **Python 版本**：{bdg-danger-line}`3.10.* / 3.11.*`
 
-    本项目依赖特定 Python 版本，其他版本暂不受支持：
+    默认使用 Python 3.10。
 
     | Python 版本 | 支持状态 |
     | :---------: | :------: |
     |    ≤ 3.9    |    ❌    |
     |    3.10     |    ✅    |
-    |   ≥ 3.11    |    ❌    |
+    |    3.11     |    ✅    |
+    |   ≥ 3.12    |    ❌    |
+
+    Unitree 硬件部署与 `--all` 仅支持 Python 3.10；Unitree 机器人模型的仿真与训练可使用 Python 3.11。
 
 -   **包管理器**：{bdg-danger-line}`UV`
 
@@ -46,7 +49,9 @@ cd MotrixLab
 在仓库根目录执行以下命令安装运行环境（Windows 上请在 PowerShell 中执行 `install.ps1`；若执行策略受限，改用 `powershell -ExecutionPolicy Bypass -File install.ps1`）：
 
 ```bash
-sh install.sh
+sh install.sh  # 默认 Python 3.10
+# 不含 Unitree 硬件部署插件的 Python 3.11 运行环境：
+sh install.sh --python 3.11
 ```
 
 该命令会自动探测 GPU 厂商（NVIDIA → CUDA，AMD → ROCm），安装运行环境所需的 workspace package、对应的
@@ -99,7 +104,8 @@ source .venv/bin/activate
 sh install.sh --all
 ```
 
-`--all` 会把所有依赖一次性全部启用：开发工具链、测试依赖、全部训练后端
+`--all` 包含 Unitree 硬件部署插件，因此仅支持 Python 3.10，不能与 `--python 3.11` 组合。
+它会把所有依赖一次性全部启用：开发工具链、测试依赖、全部训练后端
 （SKRL Torch 为必需项；`--skrl-jax` 和 `--rslrl` 添加可选后端）与文档工具。在 ROCm 下，CUDA-only
 extra（例如 SKRL JAX）会被跳过。也可以按需选择额外依赖，例如 `sh install.sh --docs` 只添加文档工具链。
 
@@ -110,7 +116,8 @@ workspace plugin；`--all` 才会安装全部 workspace package 与支持的开
 
 | 参数 | 可选值 | 说明 |
 | ---- | ------ | ---- |
-| `--all` | — | 完整开发环境：把下述所有依赖一次性全部启用（开发工具链、测试依赖、全部训练后端与文档工具） |
+| `--python` | `3.10`<br>`3.11` | 选择 Python 版本；默认 `3.10`，`3.11` 仅用于不含 Unitree 硬件部署插件的运行环境 |
+| `--all` | — | 完整开发环境，包含 Unitree，仅支持 Python 3.10（开发工具链、测试依赖、全部训练后端与文档工具） |
 | （无参数） | — | 运行环境；自动探测 GPU 厂商（NVIDIA → CUDA，AMD → ROCm，无法探测时回退 CUDA） |
 | `--gpu` | `cuda`<br>`rocm` | 指定 torch wheel 来源，覆盖自动探测 |
 | `--skrl-torch` | — | 兼容性参数；SKRL Torch 已由根项目作为必需依赖提供 |