@@ -158,7 +158,7 @@ manually specify each plugin with :option:`-p` or :envvar:`PYTEST_PLUGINS`, you
158158
159159 .. code-block :: bash
160160
161- pytest --disable-plugin-autoload -p NAME, NAME2
161+ pytest --disable-plugin-autoload -p NAME -p NAME2
162162
163163 .. tab :: toml
164164
@@ -180,3 +180,31 @@ manually specify each plugin with :option:`-p` or :envvar:`PYTEST_PLUGINS`, you
180180 .. versionadded :: 8.4
181181
182182 The :option: `--disable-plugin-autoload ` command-line flag.
183+
184+ .. note ::
185+
186+ :option: `-p ` and :envvar: `PYTEST_PLUGINS ` are both ways to explicitly control which
187+ plugins are loaded, but they serve slightly different use-cases.
188+
189+ * :option: `-p ` loads (or disables with ``-p no:<name> ``) a plugin by name or entry point
190+ for a specific pytest invocation, and is processed early during startup.
191+ * :envvar: `PYTEST_PLUGINS ` is a comma-separated list of Python modules that are imported
192+ and registered as plugins during startup. This mechanism is commonly used by test
193+ suites, for example when testing a plugin.
194+
195+ When explicitly controlling plugin loading (especially with
196+ :envvar: `PYTEST_DISABLE_PLUGIN_AUTOLOAD ` or :option: `--disable-plugin-autoload `),
197+ avoid specifying the same plugin via multiple mechanisms. Registering the same plugin
198+ more than once can lead to errors during plugin registration.
199+
200+ Examples:
201+
202+ .. code-block :: bash
203+
204+ # Disable auto-loading and load only specific plugins for this invocation
205+ PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -p xdist
206+
207+ .. code-block :: bash
208+
209+ # Disable auto-loading and load plugin modules during startup
210+ PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTEST_PLUGINS=mymodule.plugin,xdist pytest
0 commit comments