---
id: cucumber-tag-expressions
version: "11.0.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# cucumber-tag-expressions — Provides a tag-expression parser and evaluation logic for cucumber/behave

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

## What it is and what it does

Cucumber Tag Expressions is a parser and evaluator for boolean tag expressions used in Gherkin-based BDD testing. It takes a human-readable expression like `@fast and not @slow` or `(@login or @registration) and @critical`, parses it into an evaluable form, and then checks whether a given set of tags satisfies that expression. The package has no runtime dependencies and is designed to integrate with test runners like behave, which use tag expressions to filter which scenarios to execute.

The typical workflow is: a test runner receives a tag expression from the command line (e.g., `--tags="@smoke and not @wip"`), passes it to this package's `parse()` function, and then evaluates the resulting object against the tags on each scenario. It supports the full boolean algebra of `and`, `or`, and `not` operators, with parentheses for grouping, making it possible to express complex filtering logic in a readable, declarative way.

Use it for:

- Filter which test scenarios to run in CI/CD pipelines by tag expression (e.g., run only @smoke tests on every commit).
- Locally run a subset of scenarios during development using tag expressions (e.g., `@wip and not @slow`).
- Implement custom test selection logic in a test harness that needs to parse and evaluate tag-based filters.
- Build a test reporting or filtering tool that accepts user-supplied tag expressions to organize test results.
- Enforce test categorization in BDD frameworks by evaluating which scenarios match complex tag criteria.

## Worth the install?

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

Parses and evaluates boolean tag expressions (using and, or, not operators) to select Gherkin scenarios and features based on their tags, commonly used by BDD test runners like behave.

Yes. This is a lightweight, actively maintained library with zero dependencies, permissive licensing, and a clear, focused purpose. Install it if you are building or using a Gherkin-based BDD test runner (such as behave) or need to parse and evaluate tag expressions for test selection. No security vulnerabilities are known.

## Install

pip install cucumber-tag-expressions
uv add cucumber-tag-expressions
poetry add cucumber-tag-expressions

## Installing cucumber-tag-expressions

Before you install: Low friction: pure Python wheel with no runtime dependencies and active maintenance (last commit 2026-08-14). Supports current Python versions (3.10–3.14).

License in practice: MIT license permits unrestricted use, modification, and distribution in commercial and private projects.

Quickstart:

pip install cucumber-tag-expressions

from cucumber_tag_expressions import parse

fast = parse("@fast")
print(fast({"@fast", "@wip"}))  # True
print(fast({"@performance", "@slow"}))  # False

Requires Python 3.10 or later.

Verify before relying:

- Whether the package is used by test runners other than behave or if behave integration is automatic.
- Performance characteristics when evaluating complex expressions against large tag sets.

## Package facts

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

## Tags

gherkin tag expression parser, cucumber tag selector, behave tag filtering, boolean tag expressions, bdd scenario tagging, tag-based test selection, bdd-testing, gherkin, tag-filtering

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