pytest-dev/pytest · error · UsageError

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

Error message

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

What it means

Raised when the --pdbcls command-line option (or usepdb_cls ini option) specifies a debugger class that cannot be imported or resolved. pytest takes a 'module:ClassName' (or 'module:dotted.path.Class') string, imports the module, then walks the dotted attribute path; any ImportError, AttributeError, or other exception during this is wrapped as a UsageError naming the offending value and the underlying exception.

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 98b357f69e)

Solutions

1. Install the debugger package: pip install pdbpp (or ipdb).
2. Verify the import works: python -c 'import mymodule; print(mymodule.MyPdb)'.
3. Use the default pdb: remove --pdbcls / usepdb_cls.
4. Double-check the class path including any intermediate attributes (e.g. 'module:pkg.Class').

Example fix

# before
pytest --pdbcls=ppdb:Pdb  # typo, package is pdbpp

# after
pip install pdbpp
pytest --pdbcls=pdbpp:Pdb

import importlib
def resolve_pdbcls(spec: str):
    modname, _, classname = spec.partition(':')
    mod = importlib.import_module(modname)
    obj = mod
    for part in classname.split('.'):
        obj = getattr(obj, part)
    return obj
# call before pytest: resolve_pdbcls('pdbpp:Pdb') to fail fast with a clear error

import importlib
def pdbcls_resolvable(spec: str) -> bool:
    try:
        modname, _, classname = spec.partition(':')
        obj = importlib.import_module(modname)
        for part in classname.split('.'):
            obj = getattr(obj, part)
        return isinstance(obj, type)
    except Exception:
        return False

try:
    cls = resolve_pdbcls(user_spec)
except Exception as exc:
    raise ValueError(f'--pdbcls: could not import {user_spec!r}: {exc}') from exc

When it happens

Trigger: Running pytest --pdbcls=mydebugger:Pdb when 'mydebugger' isn't installed; --pdbcls=pdb:Nonexistent; --pdbcls=badmodule:goodpath.GoodClass where badmodule fails to import. The import/getattr block at line 125-132 raises, caught at 133-137.

Common situations: Specifying pdbpp/ipdb without installing them; typos in the module or class name; debugger class moved/renamed between versions; environment where the debugger package isn't installed; specifying a class path that requires a submodule not auto-imported.

Related errors

• -o/--override-ini expects option=value style (got: {ini_conf
• Directory '{rootdir}' not found. Check your '--rootdir' opti
• {exc_message}: {e.text}: at column {e.offset}: {e.msg}
• plugin {name} cannot be disabled
• Blocking conftest files using -p is not supported: -p no:{na

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