diff --git a/doc/guides/west/troubleshooting.rst b/doc/guides/west/troubleshooting.rst
index bd952a6ec75..d4c075b86d6 100644
--- a/doc/guides/west/troubleshooting.rst
+++ b/doc/guides/west/troubleshooting.rst
@@ -5,6 +5,47 @@ Troubleshooting West
 
 This page covers common issues with west and how to solve them.
 
+"Error: unexpected keyword argument 'requires_workspace'"
+*********************************************************
+
+This error occurs on some Linux distributions after upgrading to west 0.7.0 or
+later from 0.6.x. For example:
+
+.. code-block:: none
+
+   $ west update
+   [... stack trace ...]
+   TypeError: __init__() got an unexpected keyword argument 'requires_workspace'
+
+This appears to be a problem with the distribution's pip; see `this comment in
+west issue 373`_ for details. Some versions of **Ubuntu** and **Linux Mint** are known to
+have this problem. Some users report issues on Fedora as well.
+
+Neither macOS nor Windows users have reported this issue. There have been no
+reports of this issue on other Linux distributions, like Arch Linux, either.
+
+.. _this comment in west issue 373:
+   https://github.com/zephyrproject-rtos/west/issues/373#issuecomment-583489272
+
+**Workaround 1**: remove the old version, then upgrade:
+
+.. code-block:: none
+
+   $ pip3 show west | grep Location: | cut -f 2 -d ' '
+   /home/foo/.local/lib/python3.6/site-packages
+   $ rm -r /home/foo/.local/lib/python3.6/site-packages/west
+   $ pip3 install --user west==0.7.0
+
+**Workaround 2**: install west in a Python virtual environment
+
+One option is to use the `venv module`_ that's part of the Python 3 standard
+library. Some distributions remove this module from their base Python 3
+packages, so you may need to do some additional work to get it installed on
+your system.
+
+.. _venv module:
+   https://docs.python.org/3/library/venv.html
+
 "invalid choice: 'build'" (or 'flash', etc.)
 ********************************************