What causes "--pdbcls: could not import {value!r}: {exc}" in pytest-dev/pytest?

Confirm the package is installed in the active environment: pip show .

pytest-dev/pytest · error · UsageError

--pdbcls: could not import

Error message

--pdbcls: could not import {value!r}: {exc}

What it means

The --pdbcls option takes a 'module:Class' (or module:a.b.Class) specifier. pytest imports the module, then walks the dotted attribute path to resolve the class. If import or attribute access fails for any reason, pytest wraps the original exception in UsageError, naming the full specifier and the underlying error so the user can diagnose.

Solutions

Confirm the package is installed in the active environment: pip show <pkg>.
Verify the class path by importing it in a Python REPL: from <module> import <Class>.
Fix the specifier to match the package's actual module and class names, e.g. --pdbcls=IPython.terminal.debugger:TerminalPdb for ipdb.

Example fix

// before
pytest --pdbcls=pdbpp:ppdb test_x.py
// after
pip install pdbpp
pytest --pdbcls=pdbpp:pdb.Pdb test_x.py

Defensive patterns

Strategy: validation

Validate before calling

import importlib

def validate_pdbcls(spec: str) -> None:
    modname, _, classname = spec.partition(':')
    assert classname, 'expected module:Class'
    mod = importlib.import_module(modname)
    obj = mod
    for part in classname.split('.'):
        obj = getattr(obj, part)
    assert callable(obj), f'{spec} did not resolve to a class'

Type guard

null

Try / catch

null

Prevention

Install the debugger package before passing --pdbcls.
Verify the module:Class path in a REPL before scripting pytest.
Pin debugger versions to avoid class-path renames.

When it happens

Trigger: --pdbcls=pdbpdb:Pdb where pdbpdb is not installed; --pdbcls=pdb:NoSuchClass (attribute missing); --pdbcls=pdbpp:pdb.Pdb where pdbpp is installed but the dotted path is wrong; import-time error inside the target module.

Common situations: Forgetting to pip install the debugger (e.g. pdbpp, ipdb); version change that renamed the class; typo in the module or class name; the module raises on import due to a missing dependency.

Related errors

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/78468f233d41b03b. Report an issue: GitHub.

Appendix: source

Thrown at src/_pytest/debugging.py:135

        usepdb_cls = cls._config.getvalue("usepdb_cls")

        if cls._wrapped_pdb_cls and cls._wrapped_pdb_cls[0] == usepdb_cls:
            return cls._wrapped_pdb_cls[1]

        if usepdb_cls:
            modname, classname = usepdb_cls

            try:
                mod = importlib.import_module(modname)

                # Handle --pdbcls=pdb:pdb.Pdb (useful e.g. with pdbpp).
                parts = classname.split(".")
                pdb_cls = getattr(mod, parts[0])
                for part in parts[1:]:
                    pdb_cls = getattr(pdb_cls, part)
            except Exception as exc:
                value = ":".join((modname, classname))
                raise UsageError(
                    f"--pdbcls: could not import {value!r}: {exc}"
                ) from exc
        else:
            import pdb

            pdb_cls = pdb.Pdb

        wrapped_cls = cls._get_pdb_wrapper_class(pdb_cls, capman)
        cls._wrapped_pdb_cls = (usepdb_cls, wrapped_cls)
        return wrapped_cls

    @classmethod
    def _get_pdb_wrapper_class(cls, pdb_cls, capman: CaptureManager | None):
        import _pytest.config

        class PytestPdbWrapper(pdb_cls):
            _pytest_capman = capman
            _continued = False

View on GitHub (pinned to 0d6fbdeffa)