From 9f39958d0300c09d7212b64921fe1c3d4a61c565 Mon Sep 17 00:00:00 2001
From: Leo <skytuhua@gmail.com>
Date: Sun, 25 Oct 2026 23:41:20 -0700
Subject: [PATCH] docs: clarify --pyargs testpaths resolution

Co-authored-by: Codex <codex@openai.com>
---
 changelog/6451.doc.rst              |  2 ++
 doc/en/example/pythoncollection.rst | 24 ++++++++++++++++++++++++
 doc/en/reference/reference.rst      |  4 ++++
 3 files changed, 30 insertions(+)
 create mode 100644 changelog/6451.doc.rst

diff --git a/changelog/6451.doc.rst b/changelog/6451.doc.rst
new file mode 100644
index 00000000000..a91e12c555d
--- /dev/null
+++ b/changelog/6451.doc.rst
@@ -0,0 +1,2 @@
+Clarified how ``--pyargs`` changes resolution of ``testpaths``, including import
+search order, glob expansion, and explicit collection arguments.
diff --git a/doc/en/example/pythoncollection.rst b/doc/en/example/pythoncollection.rst
index 3dd87a71cb7..807ecad924d 100644
--- a/doc/en/example/pythoncollection.rst
+++ b/doc/en/example/pythoncollection.rst
@@ -165,6 +165,8 @@ You can check for multiple glob patterns by adding a space between the patterns:
    for ``unittest.TestCase`` test discovery because pytest delegates
    discovery of test case methods to unittest code.
 
+.. _pyargs-testpaths:
+
 Interpreting cmdline arguments as Python packages
 -----------------------------------------------------
 
@@ -186,11 +188,33 @@ can make this change more permanently:
     # content of pytest.toml
     [pytest]
     addopts = ["--pyargs"]
+    testpaths = ["mypkg.tests"]
 
 Now a simple invocation of ``pytest NAME`` will check
 if NAME exists as an importable package/module and otherwise
 treat it as a filesystem path.
 
+When no collection arguments are given and pytest is invoked from the
+:ref:`rootdir <rootdir>`, :confval:`testpaths` supplies the default arguments.
+With the configuration above, a bare ``pytest`` collects ``mypkg.tests``.
+Explicit arguments, such as ``pytest other_tests/test_one.py``, replace these
+defaults. When invoked outside rootdir, pytest instead defaults to collecting
+from the invocation directory.
+
+With :option:`--pyargs`, entries in :confval:`testpaths` are resolved as
+importable packages or modules before falling back to filesystem paths;
+they are not expanded as filesystem globs. Without :option:`--pyargs`,
+``testpaths`` entries are filesystem patterns, including glob expansion.
+An importable package can therefore be selected instead of a local directory
+with the same name, depending on Python's import search path.
+When tests exist both locally and in an installed package, check which copy
+Python resolves and the :ref:`import mode <import-modes>` when investigating
+``ImportPathMismatchError``.
+
+Put default collection arguments in :confval:`testpaths`, not :confval:`addopts`:
+positional arguments in ``addopts`` are passed on every invocation and are not
+replaced by explicit command-line arguments.
+
 Finding out what is collected
 -----------------------------------------------
 
diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst
index 87abcc5f74d..fd3c5402813 100644
--- a/doc/en/reference/reference.rst
+++ b/doc/en/reference/reference.rst
@@ -2610,6 +2610,10 @@ passed multiple times. The expected format is ``name=value``. For example::
    File system paths may use shell-style wildcards, including the recursive
    ``**`` pattern.
 
+   With :option:`--pyargs`, entries are resolved as importable packages or modules
+   before filesystem paths, without glob expansion. See
+   :ref:`how --pyargs interacts with testpaths <pyargs-testpaths>`.
+
    Useful when all project tests are in a known location to speed up
    test collection and to avoid picking up undesired tests by accident.