Installation¶

Requirements¶

Python 3.11 or newer (tested on 3.11, 3.12, 3.13, and 3.14)
behave-model >= 1.0 (installed automatically as a dependency)
typer >= 0.12 (installed automatically as a dependency)

behave-doctor has minimal runtime dependencies — only behave-model (for .feature file parsing) and typer (for the CLI). It is pure Python, fully typed (mypy --strict clean), and works on Linux, macOS, and Windows.

From PyPI¶

The recommended way to install behave-doctor:

pip install behave-doctor

To upgrade:

pip install --upgrade behave-doctor

With pipx (isolated environment)¶

If you prefer to keep behave-doctor isolated from your project's virtual environment:

pipx install behave-doctor

With uv¶

uv pip install behave-doctor

From source¶

git clone https://github.com/MathiasPaulenko/behave-doctor.git
cd behave-doctor
pip install .

Development install¶

For contributors who want to run tests, linting, and pre-commit hooks:

git clone https://github.com/MathiasPaulenko/behave-doctor.git
cd behave-doctor
pip install -e ".[dev]"
pre-commit install

The [dev] extra installs pytest, pytest-cov, ruff, mypy, build, and pre-commit.

Verify the installation¶

behave-doctor --version

1.1.0

You can also verify the Python API is importable:

python -c "import behave_doctor; print(behave_doctor.__version__)"

Pre-commit hook¶

behave-doctor ships a pre-commit hook that runs behave-doctor scan on every commit.

Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/MathiasPaulenko/behave-doctor
    rev: v1.1.0
    hooks:
      - id: behave-doctor
        args: ["scan", "--severity", "warning", "--no-color"]

The hook scans .feature and .py files. It runs from the repository root (pass_filenames: false) so it can build the full dependency graph.

Pre-commit configuration options¶

`args` value	Effect
`--severity error`	Only fail on errors (suppress warnings).
`--severity warning`	Fail on errors and warnings (recommended).
`--no-color`	Disable ANSI colors (recommended for CI logs).
`--exclude-rules BD101`	Skip specific rules.
`--format sarif -o out`	Write SARIF output to a file.

Uninstall¶

pip uninstall behave-doctor