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