+
+### Using a python virtual environment
+
+Additionally to
+
+```bash
+sudo apt-get install python3 python3-pip
+```
+
+(from https://www.opengeosys.org/docs/devguide/getting-started/prerequisites/), do
+
+```bash
+sudo apt-get install python3-venv
+```
+
+and then you can use the `-DOGS_USE_PIP=ON` option:
+
+```bash
+cmake ../ogs -DOGS_USE_PIP=ON -DCMAKE_BUILD_TYPE="Release" -G Ninja
+```
+
+
+
## Option: Configure with a visual tool
diff --git a/web/content/docs/devguide/getting-started/prerequisites/index.md b/web/content/docs/devguide/getting-started/prerequisites/index.md
index 11f1a54b001..e949da18544 100644
--- a/web/content/docs/devguide/getting-started/prerequisites/index.md
+++ b/web/content/docs/devguide/getting-started/prerequisites/index.md
@@ -212,9 +212,14 @@ git config --global http.proxy http://yourproxy.example.com
-Install CMake via Kitware's APT Repository by [following their instructions](https://apt.kitware.com/).
+Install CMake using system package manager, *e.g.* on Ubuntu
+
+```bash
+sudo apt install cmake
+```
For other Linux distributions you want to use your distributions package manager, [pip](https://pypi.org/project/cmake/) or [snap](https://snapcraft.io/cmake).
+
diff --git a/web/content/docs/devguide/packages/python-env/index.md b/web/content/docs/devguide/packages/python-env/index.md
index 82472e21307..fbdba5d7c91 100644
--- a/web/content/docs/devguide/packages/python-env/index.md
+++ b/web/content/docs/devguide/packages/python-env/index.md
@@ -24,6 +24,36 @@ Python packages are usually installed via `pip` inside an isolated environment (
When configuring OGS with `OGS_USE_PIP=ON` Python creates a new virtual environment in the `.venv`-directory inside your build directory. It will also install required Python packages into this environment. You can see the current environment definition in the file `requirements.txt` inside your build-directory.
+Make sure, that you did
+
+```bash
+sudo apt-get install python3 python3-pip
+sudo apt-get install python3-venv
+```
+
+then you can use the `-DOGS_USE_PIP=ON` option:
+
+```bash
+cmake ../ogs -DOGS_USE_PIP=ON -DCMAKE_BUILD_TYPE="Release" -G Ninja
+```
+
+When configuring OGS with `OGS_USE_PIP=ON`, Python creates a new virtual
+environment in the .venv-directory inside your build directory.
+It will also install required Python packages into this environment.
+For example, ogstools or Jupyter will this way be available ready-made in a
+consistent configuration.
+You can see the current environment definition with all the included packages in
+the file requirements.txt inside your build-directory.
+
+When you want to use the python packages in this virtual environment, you need
+to activate it by
+
+```bash
+source /.envrc
+```
+
+where `.envrc` is a little script including `source .venv/bin/activate` as well as some path settings.
+
To manually add Python packages run the following inside your build-directory:
```bash
diff --git a/web/content/docs/devguide/troubleshooting/cmake/index.md b/web/content/docs/devguide/troubleshooting/cmake/index.md
index c2a7e802cbf..29ba8487ddd 100644
--- a/web/content/docs/devguide/troubleshooting/cmake/index.md
+++ b/web/content/docs/devguide/troubleshooting/cmake/index.md
@@ -15,7 +15,9 @@ If something goes wrong when running CMake please try again with an **empty** or
Please read the CMake output carefully. Often it will tell you what went wrong.
-Also consider using the command line for CMake configuration as lots of CMake options (which modify requirements on third-party libraries) have to be set via the command line **before** CMake ran for the first time. E.g. when building with PETSc the following fails:
+Also consider using the command line for CMake configuration as lots of CMake options (which modify requirements on third-party libraries) have to be set via the command line **before** CMake ran for the first time.
+
+For example when building with PETSc the following fails:
- Creating build directory
- Starting CMake GUI
@@ -39,3 +41,21 @@ The following options are affected by this behavior and **should not be changed*
- `OGS_USE_PETSC`
- `CMAKE_BUILD_TYPE`
- `BUILD_SHARED_LIBS`
+
+If the errors are related to TFEL, HDF5, PETSc or VTK, you may delete `~/.cache/CPM/_ext` and try again.
+
+If there are incompatibilities to a system-installed library, e.g. HDF5, you can also use the additional cmake options, e.g. `-DOGS_BUILD_HDF5=ON`, to force a local library (in this case HDF5) build. These options are available:
+
+- `OGS_BUILD_HDF5`
+- `OGS_BUILD_TFEL`
+- `OGS_BUILD_PETSC`
+- `OGS_BUILD_VTK`
+
+External dependencies are cached in `~/.cache/CPM/`.
+If something goes wrong during the first build, then ogs will pick up the failed
+build during subsequent cmake-runs without showing any error messages from the
+dependency.
+In that case you need to delete the corresponding folder in the CPM cache,
+usually something like `~/.cache/CPM/_ext/TFEL/[some long hash]`.
+Then the next cmake-run will retrigger a build of the dependency. This applies
+to TFEL, HDF5, PETSc and VTK.