diff --git a/ports/esp32/Makefile b/ports/esp32/Makefile
index 25001643ee..bb25477444 100644
--- a/ports/esp32/Makefile
+++ b/ports/esp32/Makefile
@@ -82,6 +82,15 @@ ifeq ($(ESPIDF_CURHASH),$(ESPIDF_SUPHASH_V3))
 $(info Building with ESP IDF v3)
 else ifeq ($(ESPIDF_CURHASH),$(ESPIDF_SUPHASH_V4))
 $(info Building with ESP IDF v4)
+
+PYPARSING_VERSION = $(shell python3 -c 'import pyparsing; print(pyparsing.__version__)')
+ifneq ($(PYPARSING_VERSION),2.3.1)
+$(info ** ERROR **)
+$(info EDP IDF requires pyparsing version less than 2.4)
+$(info You will need to set up a Python virtual environment with pyparsing 2.3.1)
+$(info Please see README.md for more information)
+$(error Incorrect pyparsing version)
+endif
 else
 $(info ** WARNING **)
 $(info The git hash of ESP IDF does not match the supported version)
diff --git a/ports/esp32/README.md b/ports/esp32/README.md
index 31347b6a2a..2c7351ee53 100644
--- a/ports/esp32/README.md
+++ b/ports/esp32/README.md
@@ -26,14 +26,17 @@ There are two main components that are needed to build the firmware:
   different to the compiler used by the ESP8266)
 - the Espressif IDF (IoT development framework, aka SDK)
 
-The ESP-IDF changes quickly and MicroPython only supports a certain version. The
-git hash of this version can be found by running `make` without a configured
-`ESPIDF`. Then you can fetch only the given esp-idf using the following command:
+The ESP-IDF changes quickly and MicroPython only supports certain versions. The
+git hash of these versions (one for 3.x, one for 4.x) can be found by running
+`make` without a configured `ESPIDF`. Then you can fetch only the given esp-idf
+using the following command:
 
     $ git clone https://github.com/espressif/esp-idf.git
     $ git checkout <Current supported ESP-IDF commit hash>
     $ git submodule update --init --recursive
 
+Note: The ESP IDF v4.x support is currently experimental.
+
 The binary toolchain (binutils, gcc, etc.) can be installed using the following
 guides:
 
@@ -53,9 +56,13 @@ You will also need either Python 2 or Python 3, along with the `pyserial` and
 (when building you can use, eg, `make PYTHON=python2` to specify the version
 used).  To install the required packages do:
 ```bash
-$ pip install pyserial pyparsing
+$ pip install pyserial 'pyparsing<2.4'
 ```
 
+It is recommended to use a Python virtual environment if your system package
+manager already provides these libraries, especially as the IDF v4.x is
+currently incompatible with pyparsing 2.4 and higher.
+
 Once everything is set up you should have a functioning toolchain with
 prefix xtensa-esp32-elf- (or otherwise if you configured it differently)
 as well as a copy of the ESP-IDF repository. You will need to update your `PATH`