diff --git a/docs/contribute.md b/docs/contribute.md
index d7cf04c582..e18bf7a21c 100644
--- a/docs/contribute.md
+++ b/docs/contribute.md
@@ -84,6 +84,13 @@ Here are the steps to follow:
         ```shell
         poetry env use 3.8.11
         ```
+      
+    - Preinstall gym 0.21.0 with appropriate option to avoid an error during installation 
+      (see this [issue](https://github.com/openai/gym/issues/3176) 
+      and this [solution](https://github.com/python-poetry/poetry/issues/3433#issuecomment-840509576)):
+        ```shell
+        poetry run pip install gym==0.21.0 --no-use-pep517
+        ```
 
     - Install all dependencies as defined in `poetry.lock`, build and install the c++ library.
         ```shell
@@ -122,6 +129,13 @@ as it can also be installed by conda via the conda-forge channel.
     poetry self add poetry-dynamic-versioning
     ```
 
+- Preinstall gym 0.21.0 with appropriate option to avoid an error during installation 
+  (see this [issue](https://github.com/openai/gym/issues/3176) 
+  and this [solution](https://github.com/python-poetry/poetry/issues/3433#issuecomment-840509576)):
+    ```shell
+    poetry run pip install gym==0.21.0 --no-use-pep517
+    ```
+
 - Install all dependencies as defined in `poetry.lock`, build and install the c++ library.
     ```shell
     rm -rf build  # removing previous build
diff --git a/docs/install.md b/docs/install.md
index 0e4d312cf0..658fe11ec8 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -122,3 +122,20 @@ Alternatively you can choose to only install the core library, which is enough i
 pip install -U pip
 pip install -U scikit-decide
 ```
+
+## Troubleshooting
+
+You may encounter an [error when installing `gym==0.21.0`](https://github.com/openai/gym/issues/3176) which happens to be a dependency of `scikit-decide[all]`. This is because its installation does not
+respect PEP 517 which is enforced by default by last versions of pip and setuptools. The solution is to install it beforehand:
+```shell
+pip install -U pip 
+pip install wheel  # necessary to make work the following option
+pip install gym==0.21.0 --no-use-pep517
+pip install -U scikit-decide[all]
+```
+
+::: tip Note
+Newer versions of gym or [gymnasium](https://gymnasium.farama.org/), typically greater than 0.26 are not yet possible 
+because of a conflict between [`ray[rllib]`](https://github.com/ray-project/ray/issues/34396) 
+and [`stable-baselines3`](https://github.com/DLR-RM/stable-baselines3/issues/1452).
+:::
\ No newline at end of file