pytest-dev/pytest · error · ValueError

Specifying plugins as objects is not supported in pytester s

Error message

Specifying plugins as objects is not supported in pytester subprocess mode; specify by name instead: {plugin}

What it means

Raised by Pytester.runpytest_subprocess when any entry in self.plugins is not a string. Subprocess mode launches a fresh Python interpreter and can only activate plugins by importable name (passed as '-p name'); it cannot serialize live plugin objects across the process boundary. Object plugins are only supported by the inprocess runner.

Source

Thrown at src/_pytest/pytester.py:1515

        ``-p`` command line option.  Additionally ``--basetemp`` is used to put
        any temporary files and directories in a numbered directory prefixed
        with "runpytest-" to not conflict with the normal numbered pytest
        location for temporary files and directories.

        :param args:
            The sequence of arguments to pass to the pytest subprocess.
        :param timeout:
            The period in seconds after which to timeout and raise
            :py:class:`Pytester.TimeoutExpired`.
        :returns:
            The result.
        """
        __tracebackhide__ = True
        p = make_numbered_dir(root=self.path, prefix="runpytest-", mode=0o700)
        args = (f"--basetemp={p}", *args)
        for plugin in self.plugins:
            if not isinstance(plugin, str):
                raise ValueError(
                    f"Specifying plugins as objects is not supported in pytester subprocess mode; "
                    f"specify by name instead: {plugin}"
                )
            args = ("-p", plugin, *args)
        args = self._getpytestargs() + args
        return self.run(*args, timeout=timeout)

    def spawn_pytest(self, string: str, expect_timeout: float = 10.0) -> pexpect.spawn:
        """Run pytest using pexpect.

        This makes sure to use the right pytest and sets up the temporary
        directory locations.

        The pexpect child is returned.
        """
        basetemp = self.path / "temp-pexpect"
        basetemp.mkdir(mode=0o700)
        invoke = " ".join(map(str, self._getpytestargs()))

View on GitHub (pinned to 98b357f69e)

Solutions

  1. Register the plugin by its entry-point/module name string instead of the object when using subprocess mode.
  2. Use runpytest_inprocess() for the runs that need object plugins.
  3. Make the plugin installable/importable and pass its module name (e.g. 'mypkg.plugin').

Example fix

// before
pytester.makepyfile("def test(x): assert x==1")
pytester.runpytest_subprocess(MyPlugin())  # object not allowed
// after
# register plugin by name and use inprocess for object plugins
pytester.runpytest_inprocess(MyPlugin())
# or install plugin and pass name for subprocess
pytester.runpytest_subprocess("-p", "myplugin")
Defensive patterns

Strategy: validation

Validate before calling

def plugins_for_mode(plugins, method: str):
    if method == "subprocess":
        bad = [p for p in plugins if not isinstance(p, str)]
        if bad:
            raise ValueError(f"these plugins must be passed by name in subprocess mode: {bad}")
    return plugins

Type guard

def all_str(plugins) -> bool:
    return all(isinstance(p, str) for p in plugins)

Try / catch

try:
    pytester.runpytest_subprocess(*plugins)
except ValueError:
    # fall back to inprocess for object plugins
    pytester.runpytest_inprocess(*plugins)

Prevention

When it happens

Trigger: Passing a plugin class or module instance to the pytester fixture (pytester_factory plugins=[MyPlugin()]) and then calling runpytest_subprocess or runpytest with method='subprocess'.

Common situations: Writing a pytester test that needs a fixture-providing plugin object and switching the run to subprocess mode (e.g. to test import-time behavior); forgetting that the default method can be flipped globally via --runpytest=subprocess.

Related errors

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/e6162192eb1b3b71.json. Report an issue: GitHub.