FAQ

Why does the plugin not run without --pep723-check?

The plugin is opt-in to avoid interfering with normal test runs. PEP 723 validation is a static check that should run alongside your test suite, not replace it.

How do I handle conda-only packages?

Conda-only packages (e.g. tblite, ira_mod, ovito) cannot appear in PEP 723 inline metadata because uv can only install from PyPI. These packages are typically imported conditionally at runtime.

Add them to the ignore list:

[tool.pytest.ini_options]
pep723_ignore_imports =
    tblite
    ira_mod
    ovito

My package’s import name differs from its PyPI name

Use pep723_extra_mappings:

[tool.pytest.ini_options]
pep723_extra_mappings =
    myspecial=my-special-pkg

The plugin already handles common cases like PIL -> pillow and sklearn -> scikit-learn. See import mappings for the full list.

Can I run only PEP 723 checks in CI?

Yes, use the pep723 marker:

pytest --pep723-check -m pep723

This skips all other tests and runs only the PEP 723 validation.

What about lazy/conditional imports?

The plugin uses Python’s AST to extract all import statements in the file, including those inside if blocks, try/except, or function bodies. This is intentional: if a code path can be reached, the dependency must be available.

If you have imports that are truly optional (e.g. behind a try/except ImportError), add them to pep723_ignore_imports.

Does it check requires-python?

No. The plugin only validates the dependencies list against the file’s imports. Python version constraints are not checked.