diff --git a/doc/source/modules/pydefix.rst b/doc/source/modules/pydefix.rst
index f6828420..215a5dde 100644
--- a/doc/source/modules/pydefix.rst
+++ b/doc/source/modules/pydefix.rst
@@ -103,6 +103,9 @@ The python script `pydefix_example.py` initializes the initial condition of the
 Troubleshooting
 ---------------
 
+Pybind11 not found by cmake
+++++++++++++++++++++++++++++
+
 It during configuration stage, you get::
 
   CMake Error at CMakeLists.txt:122 (find_package):
@@ -124,3 +127,14 @@ You can then exit the interpreter and set the pybind11_DIR environement variable
   export pybind11_DIR=env/lib/python3.10/site-packages/pybind11
 
 you can then run cmake which should be able to find pybind11, and compile the code.
+
+Using pydefix in a virtual environment
++++++++++++++++++++++++++++++++++++++++
+If you use pydefix in a python virtual environment (venv), pydefix might not detect your environment and fail to find pybind11 or other
+python packages in your venv. This typically results in a python error "xxxx module not found" when you run Idefix with pydefix.
+
+The fix is to force the following environement variables (replace XX by your python version) before launching Idefix:
+
+```bash
+export PYTHONPATH=$VIRTUAL_ENV/lib/python3.XX/site-packages:$PYTHONPATH
+```