diff --git a/CMakeLists.txt b/CMakeLists.txt
index 990d9904a8e496932a926a54f61b95fab12fa65a..7205295fa7f36fd37d7837114cead443626e0293 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -371,7 +371,7 @@ if( WALBERLA_OPTIMIZE_FOR_LOCALHOST )
         add_flag ( CMAKE_CXX_FLAGS "-march=native" )
         add_flag ( CMAKE_C_FLAGS   "-march=native" )
       endif()
-      
+
       if( WALBERLA_CXX_COMPILER_IS_INTEL )
         add_flag ( CMAKE_CXX_FLAGS "-xhost" )
         add_flag ( CMAKE_C_FLAGS   "-xhost" )
@@ -570,8 +570,20 @@ if ( WALBERLA_CXX_COMPILER_IS_MSVC )
 endif ( )
 ############################################################################################################################
 
+############################################################################################################################
+##
+## Python
+##
+#############################################################################################################################
 
-
+if ( WALBERLA_BUILD_WITH_CODEGEN OR WALBERLA_BUILD_WITH_PYTHON )
+   if ( DEFINED PYTHON_ROOT_DIR OR DEFINED PYTHON_EXECUTABLE )
+      message( WARNING "Setting PYTHON_ROOT_DIR or PYTHON_EXECUTABLE will likely not work. Use Python_ROOT_DIR instead." )
+   endif ()
+   cmake_policy( SET CMP0094 NEW )
+   set( Python_FIND_FRAMEWORK LAST )
+   find_package( Python COMPONENTS Interpreter Development )
+endif ()
 
 ############################################################################################################################
 ##
@@ -579,8 +591,6 @@ endif ( )
 ##
 #############################################################################################################################
 if ( WALBERLA_BUILD_WITH_CODEGEN )
-   set( Python_FIND_FRAMEWORK LAST )
-    find_package (Python COMPONENTS Interpreter Development)
    execute_process(COMMAND ${Python_EXECUTABLE} -c "import lbmpy"
          RESULT_VARIABLE LBMPY_FOUND )
     if(NOT LBMPY_FOUND EQUAL 0)
@@ -609,9 +619,6 @@ endif()
 ##
 #############################################################################################################################
 if ( WALBERLA_BUILD_WITH_PYTHON )
-   set( Python_FIND_FRAMEWORK LAST )
-    find_package( Python COMPONENTS Interpreter Development REQUIRED)
-
     if(WALBERLA_CXX_COMPILER_IS_INTEL)
         # Intel C++17 support introduced in 2.6.2 (https://github.com/pybind/pybind11/pull/2729)
         set(PYBIND11_MINIMUM_VERSION "2.6.2")
diff --git a/README.md b/README.md
index bca339ae96fdaff55538741d951e82e5fb6440a6..dcacbe96cbcb38e97331e683451674754d80e2f5 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,38 @@ build system. Furthermore, you need an MPI library (like
 processing capabilities. All of these dependencies are typically available in
 your operating system's package manager.
 
+### CMake
+
+The typical steps, assuming your are in the waLBerla source directory, are:
+
+- `mkdir build; cd build` create a build directory and change into it
+- `cmake ..` call CMake with the waLBerla source directory as an argument
+- `make` build waLBerla
+
+To specify a CMake option you need to use `-D(Option)=(Value)`. For example to set the C++ compiler one can use:
+`cmake -DCMAKE_CXX_COMILER=clang++`
+
+To list and modify the CMake options the `ccmake` tool can be used. Just call `ccmake .` in your **build** directory to see and change the
+CMake options and variables.
+
+Some important CMake variables:
+
+- `WALBERLA_BUILD_WITH_CODEGEN` Enable pystencils code generation"
+- `Python_ROOT_DIR` Specify the directory of the `python` executable. e.g. `~/miniconda/bin/`
+- `MPI_HOME` Specify the base directory of the MPI installation.
+- `WALBERLA_BUILD_WITH_PYTHON` Support for embedding Python
+- `WALBERLA_BUILD_WITH_CUDA` Enable CUDA support
+
+For a full list of CMake Option see the [CMakeLists.txt](CMakeLists.txt) file or use `ccmake` as described above.
+
+### Codegen and Python
+
+To use the `lbmpy`/`pystencils` code generation please install the packages with e.g. `pip3 install lbmpy` and specify the correct python
+environment when calling CMake.
+
+In previous versions of CMake one could use `PYTHON_EXECUTABLE` or `PYTHON_ROOT_DIR` (all upper case) to specify the python executable or
+the directory. This does **NOT** work anymore. Please use `Python_ROOT_DIR`.
+
 ## Get involved
 
 ### Contributing
@@ -48,29 +80,29 @@ Many thanks go to waLBerla's [contributors](AUTHORS.txt)
 If you use waLBerla in a publication, please cite the following articles:
 
 Overview:
-  - M. Bauer et al, *waLBerla: A block-structured high-performance framework for
-    multiphysics simulations*. Computers & Mathematics with Applications, 2020.
-    https://doi.org/10.1016/j.camwa.2020.01.007.
+- M. Bauer et al, *waLBerla: A block-structured high-performance framework for
+  multiphysics simulations*. Computers & Mathematics with Applications, 2020.
+  https://doi.org/10.1016/j.camwa.2020.01.007.
 
 Grid Refinement:
-  - F. Schornbaum and U. Rüde, *Massively parallel algorithms for the lattice boltzmann
-    method on nonuniform grids*. SIAM Journal on Scientific Computing, 2016.
-    https://doi.org/10.1137/15M1035240
+- F. Schornbaum and U. Rüde, *Massively parallel algorithms for the lattice boltzmann
+  method on nonuniform grids*. SIAM Journal on Scientific Computing, 2016.
+  https://doi.org/10.1137/15M1035240
 
 LBM - Particle Coupling:
-  - C. Rettinger and U. Rüde, *A comparative study of fluid-particle coupling methods for
-    fully resolved lattice Boltzmann simulations*. Computers & Fluids, 2017.
-    https://doi.org/10.1016/j.compfluid.2017.05.033
+- C. Rettinger and U. Rüde, *A comparative study of fluid-particle coupling methods for
+  fully resolved lattice Boltzmann simulations*. Computers & Fluids, 2017.
+  https://doi.org/10.1016/j.compfluid.2017.05.033
 
 MESA-PD:
-  - S. Eibl and U. Rüde, *A Modular and Extensible Software Architecture for Particle Dynamics*.
-    Proceedings Of The 8Th International Conference On Discrete Element Methods.
-    https://mercurylab.co.uk/dem8/full-papers/#page-content
+- S. Eibl and U. Rüde, *A Modular and Extensible Software Architecture for Particle Dynamics*.
+  Proceedings Of The 8Th International Conference On Discrete Element Methods.
+  https://mercurylab.co.uk/dem8/full-papers/#page-content
 
 Carbon Nanotubes:
-  - G. Drozdov et al, *Densification of single-walled carbon nanotube films:
-    Mesoscopic distinct element method simulations and experimental validation*.
-    Journal of Applied Physics, 2020. https://doi.org/10.1063/5.0025505
+- G. Drozdov et al, *Densification of single-walled carbon nanotube films:
+  Mesoscopic distinct element method simulations and experimental validation*.
+  Journal of Applied Physics, 2020. https://doi.org/10.1063/5.0025505
 
 ## License