gherkin-official

library42.0.1pypypi✓ verified 24d ago

Gherkin parser (official, by Cucumber team). It is a parser and compiler for the Gherkin language, which is a business-readable, domain-specific language used in Behavior-Driven Development (BDD) to describe software's behavior. It is developed and maintained by the Cucumber team and is designed to produce easily consumable Abstract Syntax Tree (AST) and Pickle objects. As of version 39.0.0, it officially supports Python versions 3.9 through 3.13. Releases are frequent, aligning with the broader Cucumber ecosystem development.

testing

pip install gherkin-official

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · GHERKIN-OFFICIAL

gherkin-official

testingpythonv42.0.1

Install

1.7s avg

Import

85ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v42.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.090s · 18.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.080s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ from gherkin import Parser

✗ import gherkin; parser = gherkin.Parser()

The Parser class is directly available from the `gherkin` package, not a top-level `gherkin` object that needs instantiation or deeper module access.

Compiler

✓ from gherkin import Compiler

This quickstart demonstrates how to parse Gherkin feature text into a Gherkin Document Abstract Syntax Tree (AST) and then compile it into 'Pickle' objects, which are simplified representations suitable for execution. It also shows basic access to the parsed data.

from gherkin import Parser, Compiler feature_text = """ Feature: Calculator As a math enthusiast I want to add numbers So I can avoid mental arithmetic Scenario: Add two numbers Given I have entered 50 into the calculator And I have entered 70 into the calculator When I press add Then the result should be 120 """ parser = Parser() gherkin_document = parser.parse(feature_text) gherkin_document["uri"] = "test.feature" # Add a URI for the document compiler = Compiler() pickles = compiler.compile(gherkin_document) print(f"Parsed Gherkin Document: {gherkin_document}") print(f"Compiled Pickles: {pickles}") # Example of accessing data if pickles: first_pickle = pickles[0] print(f"\nFirst Pickle Name: {first_pickle['name']}") print(f"First Pickle Steps: {[step['text'] for step in first_pickle['steps']]}")

gherkin --version

Debug

Known issues

breakingPython 2 and Python 3.8 are no longer supported as of version 39.0.0. The library now requires Python 3.9 or newer.

fix

Ensure your project runs on Python 3.9 or a newer supported version.

affects: 39.0.0+

breakingThe Gherkin grammar and specification compatibility has evolved. Significant changes include: the `Feature:` keyword is now mandatory, multiline steps must consistently use triple-quotes, tags no longer permit spaces (e.g., `@tag one` is invalid), and the `Rule` keyword is now officially supported.

fix

Review and update `.feature` files to strictly adhere to the current Gherkin specification. Consult the Gherkin reference for up-to-date syntax.

affects: Primarily 8.0.0+ (reflected in tools like pytest-bdd's adoption of this parser) and 39.0.0+ for `Rule` support.

gotchaThe dedicated `cucumber/gherkin-python` GitHub repository is now read-only and archived. For active development, issues, and contributions, refer to the main polyglot `cucumber/gherkin` monorepo.

fix

Direct all development-related inquiries, bug reports, and pull requests to the main `cucumber/gherkin` repository (https://github.com/cucumber/gherkin).

affects: All versions (since the archiving of `gherkin-python` in Nov 2022).

deprecatedThe `gherkin` command-line script, which was primarily used for internal acceptance tests, has been removed.

fix

Directly use the `gherkin-official` library's Python API (`from gherkin import Parser, Compiler`) for parsing and compiling Gherkin features within your applications.

affects: 39.0.0+

gotchaIn older setups, users sometimes incorrectly tried to import from `gherkin3` or found that a direct `import gherkin` didn't expose parser methods. The correct and consistent import is `from gherkin import Parser, Compiler`.

fix

Always use `from gherkin import Parser, Compiler` to access the core functionality.

affects: Older versions prior to widespread adoption and clarity on import paths (e.g., before 27.0.0 where package name became `gherkin-official`).

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'gherkin'

The `gherkin-official` package is not installed in the Python environment, or is installed but incorrectly referenced with the simple 'gherkin' name instead of a specific submodule or the full package name.

fix

Ensure the package is installed using `pip install gherkin-official`. When importing, use specific submodules like `from gherkin.parser import Parser` or `from gherkin.token_scanner import TokenScanner`, rather than just `import gherkin`.

AttributeError: 'module' object has no attribute 'parse'

This typically occurs when a user tries to call a method like `parse()` directly on the top-level `gherkin` module (e.g., `gherkin.parse()`) after a simple `import gherkin`, without importing the specific `Parser` class from `gherkin.parser`.

fix

Import the `Parser` class explicitly from the `gherkin.parser` submodule and then instantiate and use it. For example: `from gherkin.parser import Parser; parser = Parser(); document = parser.parse(token_scanner)`.

gherkin.parser.ParseError: Parse error found X when expecting Y

This error indicates that the Gherkin parser encountered unexpected syntax in a .feature file, meaning the Gherkin document does not conform to the language specification. Common causes include incorrect keyword usage, malformed tables (e.g., `Examples` not nested under `Scenario Outline`), or comments in invalid locations.

fix

Review the Gherkin feature file for syntax errors according to the official Gherkin language specification. Pay close attention to keywords, indentation (two spaces recommended), and the structure of scenarios, outlines, and examples. Ensure comments are on their own line starting with '#' and not within tag sections or data tables.

from gherkin.token_scanner import TokenScanner ... AttributeError: 'TokenScanner' object has no attribute 'read'

The `TokenScanner` expects a string input (representing the Gherkin document content) during initialization, but it is sometimes mistakenly initialized without an argument or with an incorrect type, leading to attempts to call methods on a malformed or `None` object.

fix

Pass the Gherkin feature file content as a string when instantiating `TokenScanner`. For example: `with open('your_feature_file.feature', 'r', encoding='utf-8') as f: gherkin_content = f.read(); token_scanner = TokenScanner(gherkin_content)`.

Upgrade

Version history

42.0.1latest on PyPI · released Aug 5, 2026

Audit

Dependencies

typing-extensionsrequiredUsed for type hinting support.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/cucumber/gherkin ↗

packagehttps://pypi.org/project/gherkin-official/ ↗

homepagehttps://cucumber.io ↗

changeloghttps://github.com/cucumber/gherkin/releases ↗