No module named 'relax.spinlock'

[donghaiwang]

When run https://github.com/LNSGroup/Qflex/blob/main/scripts/train.py

hutb_3.12\python.exe D:\hutb\Build\UErobotics\Qflex\scripts\train.py --alg qflex --env MS700Locomotion-v1 --seed 100 --total_step 50000000 --num_vec_envs 224 --hidden_dim 1024 --diffusion_hidden_dim 1024 --record_video 
Traceback (most recent call last):
  File "D:\hutb\Build\UErobotics\Qflex\scripts\train.py", line 39, in <module>
    from relax.algorithm.crossq import CrossQ
  File "D:\hutb\Build\UErobotics\Qflex\relax\algorithm\crossq.py", line 18, in <module>
    from relax.network.crossq import CrossQNet, CrossQParams
  File "D:\hutb\Build\UErobotics\Qflex\relax\network\crossq.py", line 8, in <module>
    from relax.env import RelaxWrapper
  File "D:\hutb\Build\UErobotics\Qflex\relax\env\__init__.py", line 22, in <module>
    from relax.env.vector import VectorEnv, SerialVectorEnv, GymProcessVectorEnv, PipeProcessVectorEnv, SpinlockProcessVectorEnv, FutexProcessVectorEnv
  File "D:\hutb\Build\UErobotics\Qflex\relax\env\vector\__init__.py", line 5, in <module>
    from relax.env.vector.process2 import ProcessVectorEnv as SpinlockProcessVectorEnv
  File "D:\hutb\Build\UErobotics\Qflex\relax\env\vector\process2.py", line 13, in <module>
    from relax.spinlock import spinlock_server_wait, spinlock_server_wait_mask, spinlock_server_notify, spinlock_server_notify_mask
ModuleNotFoundError: No module named 'relax.spinlock'

[yunyuewei]

Hi, could you share the list of packages installed in your environment?

On my machine, MS700Locomotion-v1 runs successfully by following the README instructions:

1. Configure the environment

UV_CACHE_DIR=.uv-cache uv venv .venv/relax_ms --python 3.12 && \
UV_CACHE_DIR=.uv-cache uv pip install --python .venv/relax_ms \
  -r requirements/uv/jax-cuda12.txt \
  -r requirements/uv/relax_ms_700_walk.txt

2. Export the required environment variables

export XLA_FLAGS='--xla_gpu_deterministic_ops=true'
export CUDA_VISIBLE_DEVICES=0
export MUJOCO_GL=egl
export XLA_PYTHON_CLIENT_PREALLOCATE=false

3. Run the training script

.venv/relax_ms/bin/python scripts/train.py --alg qflex --env MS700Locomotion-v1 --seed 100 --total_step 50000000 --num_vec_envs 224 --hidden_dim 1024 --diffusion_hidden_dim 1024 --record_video

For debugging, you may want to start with a smaller num_vec_envs, for example --num_vec_envs 4, to check whether the environment can launch correctly.

[donghaiwang]

Thank you. Here is my environment.

(hutb_3.12) D:\hutb>pip list
WARNING: Ignoring invalid distribution ~axlib (D:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.12\Lib\site-packages)
Package                 Version
----------------------- -----------
absl-py                 2.4.0
annotated-types         0.7.0
asttokens               3.0.1
certifi                 2026.4.22
charset-normalizer      3.4.7
chex                    0.1.86
click                   8.3.3
cloudpickle             3.1.2
colorama                0.4.6
contourpy               1.3.3
cycler                  0.12.1
decorator               5.2.1
dill                    0.3.8
dm-haiku                0.0.16
etils                   1.14.0
executing               2.2.1
Farama-Notifications    0.0.6
fonttools               4.62.1
fsspec                  2026.4.0
gitdb                   4.0.12
GitPython               3.1.49
glfw                    2.10.0
grpcio                  1.80.0
gymnasium               1.0.0
idna                    3.13
ImageIO                 2.37.3
imageio-ffmpeg          0.6.0
ipdb                    0.13.13
ipython                 9.13.0
ipython_pygments_lexers 1.1.1
jax                     0.4.27
jaxlib                  0.4.27
jedi                    0.20.0
jmp                     0.0.4
joblib                  1.5.3
kiwisolver              1.5.0
llvmlite                0.47.0
Markdown                3.10.2
MarkupSafe              3.0.3
matplotlib              3.10.9
matplotlib-inline       0.2.1
ml_dtypes               0.5.4
moviepy                 2.1.2
mujoco                  3.8.0
multipledispatch        1.0.0
numba                   0.65.1
numpy                   2.4.4
numpyro                 0.14.0
opt_einsum              3.4.0
optax                   0.1.8
packaging               26.0
pandas                  3.0.2
parso                   0.8.7
pillow                  10.4.0
pip                     26.0.1
platformdirs            4.9.6
proglog                 0.1.12
prompt_toolkit          3.0.52
protobuf                7.34.1
psutil                  7.2.2
pure_eval               0.2.3
pydantic                2.13.3
pydantic_core           2.46.3
Pygments                2.20.0
PyOpenGL                3.1.10
pyparsing               3.3.2
python-dateutil         2.9.0.post0
python-dotenv           1.2.2
PyYAML                  6.0.3
requests                2.33.1
scikit-learn            1.8.0
scipy                   1.17.1
sentry-sdk              2.59.0
setproctitle            1.3.7
setuptools              82.0.1
six                     1.17.0
smmap                   5.0.3
stack-data              0.6.3
tabulate                0.10.0
tensorboard             2.20.0
tensorboard-data-server 0.7.2
tensorboardX            2.6.5
threadpoolctl           3.6.0
toolz                   1.1.0
tqdm                    4.67.3
traitlets               5.14.3
typing_extensions       4.15.0
typing-inspection       0.4.2
tzdata                  2026.2
urllib3                 2.6.3
wandb                   0.26.1
wcwidth                 0.7.0
Werkzeug                3.1.8
wheel                   0.46.3
zipp                    3.23.1

I'm not sure if I should use the relax.spinlock module from the repository, as this spinlock folder is missing.

[yunyuewei]

I see. It looks like the relax package has not been installed in your current environment.

You can install it in editable mode by running:

cd Qflex
pip install -e .

After that, the relax package should be available in your current Python environment.

[donghaiwang]

After running pip install -e ., I get these error: “linux/futex.h”: No such file or directory. Is it possible that this project cannot run on Windows?

(hutb_3.12) D:\hutb\Build\UErobotics\Qflex>pip install -e .
WARNING: Ignoring invalid distribution ~axlib (D:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.12\Lib\site-packages)
Obtaining file:///D:/hutb/Build/UErobotics/Qflex
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Preparing editable metadata (pyproject.toml) ... done
  WARNING: Ignoring invalid distribution ~axlib (D:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.12\Lib\site-packages)
Building wheels for collected packages: relax
  Building editable for relax (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Building editable for relax (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [21 lines of output]
      running editable_wheel
      creating C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax.egg-info
      writing C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax.egg-info\PKG-INFO
      writing dependency_links to C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax.egg-info\dependency_links.txt
      writing top-level names to C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax.egg-info\top_level.txt
      writing manifest file 'C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax.egg-info\SOURCES.txt'
      reading manifest file 'C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax.egg-info\SOURCES.txt'
      adding license file 'LICENSE'
      writing manifest file 'C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax.egg-info\SOURCES.txt'
      creating 'C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax-0.1.0.dist-info'
      C:\Users\nongf\AppData\Local\Temp\pip-build-env-mlilzg56\overlay\Lib\site-packages\setuptools\command\bdist_wheel.py:103: RuntimeWarning: Config variable 'Py_DEBUG' is unset, Python ABI tag may be incorrect
        if get_flag("Py_DEBUG", hasattr(sys, "gettotalrefcount"), warn=(impl == "cp")):
      creating C:\Users\nongf\AppData\Local\Temp\pip-ephem-wheel-cache-4axwwmih\wheels\95\db\64\8aec797dab4ce9df04c15a20ec44b0374f86fa7e7db410f462\tmpyrxu0_z5\.tmp-4l_qx4wx\relax-0.1.0.dist-info\WHEEL
      running build_py
      running build_ext
      building 'relax.futex' extension
      creating C:\Users\nongf\AppData\Local\Temp\tmp6altbcbc.build-temp\Release\src
      "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.38.33130\bin\HostX86\x64\cl.exe" /c /nologo /O2 /W3 /GL /DNDEBUG /MD -ID:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.12\Library\include -ID:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.12\include -ID:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.12\Include "-IC:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.38.33130\include" "-IC:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.38.33130\ATLMFC\include" "-IC:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\VS\include" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.26100.0\ucrt" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\um" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\shared" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\winrt" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.26100.0\\cppwinrt" "-IC:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\include\um" /Tcsrc/futex.c /FoC:\Users\nongf\AppData\Local\Temp\tmp6altbcbc.build-temp\Release\src\futex.obj
      futex.c
      src/futex.c(3): fatal error C1083: 无法打开包括文件: “linux/futex.h”: No such file or directory
      error: command 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\VC\\Tools\\MSVC\\14.38.33130\\bin\\HostX86\\x64\\cl.exe' failed with exit code 2
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building editable for relax
Failed to build relax
error: failed-wheel-build-for-install

× Failed to build installable wheels for some pyproject.toml based projects
╰─> relax

When I comment these line // #include <linux/futex.h> in futex.c, it compile and install relax-0.1.0 successfully. But we have same error: No module named 'relax.spinlock'

[yunyuewei]

Yes, the codebase has only been fully tested on Linux.

I did a quick test on Windows, and it appears to work under WSL after applying the following modification to src/futex.c:

diff --git a/src/futex.c b/src/futex.c
--- a/src/futex.c
+++ b/src/futex.c
@@
-int futex_server_wait(struct lock_t *lock, int target) {
+int futex_server_wait(struct lock_t *lock, unsigned int target) {
@@
-    atomic_uint *count = (atomic_uint *)PyLong_AsVoidPtr(args[0]);
-    if (count == NULL) {
+    struct lock_t *lock = (struct lock_t *)PyLong_AsVoidPtr(args[0]);
+    if (lock == NULL) {
         PyErr_SetString(PyExc_TypeError, "futex_server_wait() requires a valid pointer");
         return NULL;
     }
-    int target = (int)PyLong_AsLong(args[1]);
-    int status = futex_server_wait(count, target);
+    unsigned int target = (unsigned int)PyLong_AsUnsignedLong(args[1]);
+    if (PyErr_Occurred() != NULL) {
+        return NULL;
+    }
+    int status = futex_server_wait(lock, target);
@@
-    atomic_uint *addr = (atomic_uint *)PyLong_AsVoidPtr(args[0]);
-    if (addr == NULL) {
+    struct lock_t *lock = (struct lock_t *)PyLong_AsVoidPtr(args[0]);
+    if (lock == NULL) {
         PyErr_SetString(PyExc_TypeError, "futex_server_notify() requires a valid pointer");
         return NULL;
     }
     int value = (int)PyLong_AsLong(args[1]);
-    futex_server_notify(addr, value);
+    if (PyErr_Occurred() != NULL) {
+        return NULL;
+    }
+    futex_server_notify(lock, value);
@@
-    atomic_uint *addr = (atomic_uint *)PyLong_AsVoidPtr(args[0]);
-    if (addr == NULL) {
+    struct lock_t *lock = (struct lock_t *)PyLong_AsVoidPtr(args[0]);
+    if (lock == NULL) {
         PyErr_SetString(PyExc_TypeError, "futex_client_wait() requires a valid pointer");
         return NULL;
     }
     int value = (int)PyLong_AsLong(args[1]);
-    uint32_t new = futex_client_wait(addr, value);
+    if (PyErr_Occurred() != NULL) {
+        return NULL;
+    }
+    uint32_t new = futex_client_wait(lock, value);
@@
-    atomic_uint *count = (atomic_uint *)PyLong_AsVoidPtr(arg);
-    if (count == NULL) {
+    struct lock_t *lock = (struct lock_t *)PyLong_AsVoidPtr(arg);
+    if (lock == NULL) {
         PyErr_SetString(PyExc_TypeError, "futex_client_notify() requires a valid pointer");
         return NULL;
     }
-    futex_client_notify(count);
+    futex_client_notify(lock);

With this change, the codebase can run on Windows through WSL by following the README instructions. However, Linux is still the recommended platform for running the codebase, as it is the environment we primarily test and support.