diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -9,32 +9,58 @@
 
 [1]: http://myrepos.branchable.com/
 
+The provided mr config will also install a [pre-commit][2] hook in cloned
+repositories, so the `pre-commit` tool must be available as well.
+
+[2]: https://pre-commit.com/
+
 In Debian, the "mr" command is shipped in the "mr" package.
 
-Once you have installed "mr", just use the following helper for both initial
-code checkout and subsequent updates:
+Unfortunately, "pre-commit" itself is not available in Debian for now.
+
+However, we strongly suggest you use a [virtualenv][3] to manage your SWH
+development environment. You can create it using virtualenv, or you can
+use a virtualenv wrapper tool like [virtualenvwrapper][4] or [pipenv][5] (or
+any other similar tool). In Debian, both these tools are available as
+"virtualenvwrapper" and "pipenv".
+
+[3]: https://virtualenv.pypa.io/
+[4]: https://virtualenvwrapper.readthedocs.io/
+[5]: https://pipenv.readthedocs.io/
 
-    cd swh-environment
-    bin/update
+In the example below we are using virtualenv directly:
+
+```lang=shell
+git clone https://forge.softwareheritage.org/source/swh-environment.git
+cd swh-environment
+python3 -m venv .venv
+. .venv/bin/activate
+pip install pre-commit
+```
+
+then you can use the following helper for both initial code checkout and
+subsequent updates:
+
+```lang=shell
+bin/update
+```
 
 Note that the first time you run `bin/update` it will add the
 `swh-environment/.mrconfig` file to your `~/.mrtrust` (we use this to be able
-to setup pre-commit hooks upon repository checkouts). See `MR(1)` for more
-information about trusted `mr` repositories.
+to setup pre-commit hooks upon repository checkouts) and install "pre-commit"
+as git precommit hook in each git repository. See `MR(1)` for more information
+about trusted `mr` repositories.
 
 You can also checkout/update repositories by hand using `mr up`.
 
 See `.mrconfig` for the actual list of repositories.
 
 
-PYTHONPATH
-----------
-
-We use several Python modules, that should all be in the PYTHONPATH to be
-found. To that extent, we provide in this repository a script to set the
-PYTHONPATH variable to the correct value. You can use it as follows:
+Upgrade from makefile-based hooks
+---------------------------------
 
-    . pythonpath.sh
+Git pre commit hooks used to be makefile-based scripts. Running `mr update`
+will automatically replace these by the `pre-commit` tool,
 
 
 Initialize a new Python package repository
diff --git a/bin/update b/bin/update
--- a/bin/update
+++ b/bin/update
@@ -7,5 +7,11 @@
     echo "$mrconf" >> "$mrtrust"
 fi
 
+if ! which pre-commit &> /dev/null ; then
+	echo "The pre-commit command is required, please install it before"
+	echo "running this command. See README.md for more information."
+	exit 1
+fi
+
 git pull
 mr -j 4 update
diff --git a/pythonpath.sh b/pythonpath.sh
deleted file mode 100644
--- a/pythonpath.sh
+++ /dev/null
@@ -1,33 +0,0 @@
-# usage: . pythonpath
-#
-# source this file as above (do not execute it) to set the PYTHONPATH
-# environment variable to the list of directories corresponding to the
-# repositories known to mr
-
-
-# special case for bash to get the sourced script file path
-if [ -n "${BASH_VERSION}" ] ; then
-  base_path=$( dirname "${BASH_SOURCE[0]}" )
-else
-  base_path=$( dirname "$0" )
-fi
-  
-tmp_path=$(
-for dir in $( builtin cd $base_path && bin/ls-all-repos --absolute ) ; do
-    if echo "$dir" | grep -q -- '-template$' ; then
-        continue
-    fi
-    if test -d "${dir}/swh/" ; then
-        echo "$dir"
-    fi
-done \
-    | paste -d':' -s)
-
-export PYTHONPATH="$tmp_path"
-
-if [ "$1" = "-p" -o "$1" = "--print" ] ; then
-    echo $PYTHONPATH
-fi
-
-unset base_path
-unset tmp_path