diff --git a/docs/html/reference/index.rst b/docs/html/reference/index.rst
index f25568bfb15..f3312948193 100644
--- a/docs/html/reference/index.rst
+++ b/docs/html/reference/index.rst
@@ -17,3 +17,4 @@ Reference Guide
    pip_config
    pip_wheel
    pip_hash
+   pip_debug
diff --git a/docs/html/reference/pip_debug.rst b/docs/html/reference/pip_debug.rst
new file mode 100644
index 00000000000..8e8b21b5183
--- /dev/null
+++ b/docs/html/reference/pip_debug.rst
@@ -0,0 +1,28 @@
+.. _`pip debug`:
+
+pip debug
+-----------
+
+.. contents::
+
+Usage
+*****
+
+.. pip-command-usage:: debug
+
+
+.. warning::
+    This command is only meant for debugging.
+    Its options and outputs are provisional and may change without notice.
+
+
+Description
+***********
+
+.. pip-command-description:: debug
+
+
+Options
+*******
+
+.. pip-command-options:: debug
diff --git a/docs/man/commands/debug.rst b/docs/man/commands/debug.rst
new file mode 100644
index 00000000000..b27ef2b550d
--- /dev/null
+++ b/docs/man/commands/debug.rst
@@ -0,0 +1,26 @@
+:orphan:
+
+==========
+pip-debug
+==========
+
+Description
+***********
+
+.. pip-command-description:: debug
+
+Usage
+*****
+
+.. pip-command-usage:: debug
+
+
+.. warning::
+    This command is only meant for debugging.
+    Its options and outputs are provisional and may change without notice.
+
+
+Options
+*******
+
+.. pip-command-options:: debug
diff --git a/src/pip/_internal/commands/debug.py b/src/pip/_internal/commands/debug.py
index 99b5b946f8a..84d06179c06 100644
--- a/src/pip/_internal/commands/debug.py
+++ b/src/pip/_internal/commands/debug.py
@@ -91,6 +91,12 @@ def __init__(self, *args, **kw):
 
     def run(self, options, args):
         # type: (Values, List[Any]) -> int
+        logger.warning(
+            "This command is only meant for debugging. "
+            "Do not use this with automation for parsing and getting these "
+            "details, since the output and options of this command may "
+            "change without notice."
+        )
         show_value('pip version', get_pip_version())
         show_value('sys.version', sys.version)
         show_value('sys.executable', sys.executable)
diff --git a/tests/functional/test_debug.py b/tests/functional/test_debug.py
index 3f5374722da..e7a37616b60 100644
--- a/tests/functional/test_debug.py
+++ b/tests/functional/test_debug.py
@@ -15,7 +15,7 @@ def test_debug(script, args):
     Check simple option cases.
     """
     args = ['debug'] + args
-    result = script.pip(*args)
+    result = script.pip(*args, allow_stderr_warning=True)
     stdout = result.stdout
 
     assert 'sys.executable: ' in stdout
@@ -43,7 +43,7 @@ def test_debug__target_options(script, args, expected):
     Check passing target-related options.
     """
     args = ['debug'] + args
-    result = script.pip(*args)
+    result = script.pip(*args, allow_stderr_warning=True)
     stdout = result.stdout
 
     assert 'Compatible tags: ' in stdout