---
id: pytest-bdd
version: "8.1.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-bdd — BDD for pytest

License: permissive · Maintenance: active · Downloads: 3.6M/mo

## What it is and what it does

pytest-bdd is a pytest plugin that brings Gherkin-style behavior-driven development (BDD) testing into the pytest ecosystem. It lets you write human-readable feature files describing application behavior, then map those steps to Python test functions using decorators. Unlike standalone BDD tools, it integrates directly with pytest, so you can reuse pytest fixtures, combine BDD and unit tests in the same project, and avoid maintaining a separate test runner.

The package supports step parameters with multiple parser types (string, parse, cfparse, regex), step aliases for readability, and dependency injection through pytest fixtures. It handles the full BDD workflow—Given/When/Then steps, scenario outlines, and step argument parsing—while letting you leverage pytest's reporting, plugins, and configuration.

Use it for:

- Write acceptance tests in plain Gherkin that non-technical stakeholders can read and understand.
- Unify functional and unit tests in a single pytest suite, reducing test infrastructure complexity.
- Reuse existing pytest fixtures as setup and action steps in BDD scenarios via dependency injection.
- Parameterize BDD steps with multiple data types using parse or cfparse parsers for scenario coverage.
- Maintain feature documentation that stays synchronized with executable tests.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

pytest-bdd implements Gherkin-based behavior-driven development testing within pytest, allowing you to write feature files and step definitions that unify functional and unit tests.

Yes. pytest-bdd is actively maintained, permissively licensed, has no known vulnerabilities, and integrates cleanly into pytest workflows. Install it if you need BDD-style testing, want to document requirements as executable scenarios, or need to bridge technical and non-technical stakeholders. The low install friction and mature codebase make it a safe choice for projects already using pytest.

## Install

pip install pytest-bdd
uv add pytest-bdd
poetry add pytest-bdd

## Installing pytest-bdd

Before you install: Low install friction with a pure-Python wheel and seven runtime dependencies. The package is actively maintained with recent releases, 1460 repository stars, and support for modern Python versions (3.9–3.13).

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely in both open-source and commercial projects with minimal restrictions.

Quickstart:

pip install pytest-bdd

from pytest_bdd import scenario, given, when, then

@scenario('example.feature', 'Example scenario')
def test_example():
    pass

@given('a precondition')
def precondition():
    return True

Requires Python 3.9 or later; feature files must follow Gherkin syntax and be discoverable by pytest.

Verify before relying:

- Whether the package's Gherkin subset covers the full range of Gherkin constructs needed for your project.
- Performance characteristics when running large numbers of scenarios or with complex step definitions.
- Integration compatibility with other pytest plugins beyond those listed as runtime dependencies.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

BDD testing framework, Gherkin pytest plugin, behavior driven development, feature file testing, pytest BDD scenarios, acceptance testing pytest, gherkin language testing, bdd, gherkin, acceptance-testing

[View on SkillFed](https://skillfed.io/packages/pytest-bdd) · [View on PyPI](https://pypi.org/project/pytest-bdd/)