diff --git a/changelog/3375.doc.rst b/changelog/3375.doc.rst
new file mode 100644
index 000000000..f7858ff7e
--- /dev/null
+++ b/changelog/3375.doc.rst
@@ -0,0 +1 @@
+Document that using ``setup.cfg`` may crash other tools or cause hard to track down problems because it uses a different parser than ``pytest.ini`` or ``tox.ini`` files.
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 9305cbb95..92e298a88 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -889,6 +889,12 @@ Here is a list of builtin configuration options that may be written in a ``pytes
 file, usually located at the root of your repository. All options must be under a ``[pytest]`` section
 (``[tool:pytest]`` for ``setup.cfg`` files).
 
+.. warning::
+    Usage of ``setup.cfg`` is not recommended unless for very simple use cases. ``.cfg``
+    files use a different parser than ``pytest.ini`` and ``tox.ini`` which might cause hard to track
+    down problems.
+    When possible, it is recommended to use the latter files to hold your pytest configuration.
+
 Configuration file options may be overwritten in the command-line by using ``-o/--override``, which can also be
 passed multiple times. The expected format is ``name=value``. For example::