Install & Compatibility
Where this runs
tested against v2.16.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 21.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.000s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AllureFormatter
✓ behave -f allure_behave.formatter:AllureFormatter ...
Used as a Behave formatter string in command line or behave.ini
allure
✓ import allure
Main module for runtime API annotations (e.g., @allure.step, allure.dynamic.issue)
allure_report
✓ from allure_behave.hooks import allure_report
✗ behave -f allure_behave.formatter:AllureFormatter ... when using behave-parallel
Required for parallel execution setup in environment.py instead of direct formatter usage on the command line.
This quickstart demonstrates how to integrate Allure Behave with a simple Behave feature file and step definitions. It includes an example of using `@allure.step` for sub-steps and `allure.attach` for adding content to the report. The `behave.ini` configuration is shown as an alternative to command-line arguments for specifying the Allure formatter. Finally, it shows how to generate and view the interactive Allure report using the Allure Report CLI tool.
# 1. features/example.feature
Feature: Allure Behave Example
Scenario: A simple test scenario
Given I have a step
When I perform an action
Then I should see a result
# 2. steps/example_steps.py
from behave import given, when, then
import allure
@given('I have a step')
def step_have_step(context):
pass
@when('I perform an action')
def step_perform_action(context):
with allure.step('Sub-step: doing something important'):
print('Performing action...')
@then('I should see a result')
def step_see_result(context):
allure.attach('This is some attachment content.', name='Text Attachment', attachment_type=allure.attachment_type.TEXT)
assert True
# 3. behave.ini (optional, but good practice)
# [behave]
# format=allure_behave.formatter:AllureFormatter
# outfiles=allure-results
# 4. Run Behave tests and collect results
# behave -f allure_behave.formatter:AllureFormatter -o allure-results features/
# 5. Generate and open the Allure Report
# allure serve allure-results
Debug
Known issues
gotchaGenerating the final HTML Allure Report requires the Allure Report command-line tool, which is a separate Java-based dependency and needs to be installed outside of Python (e.g., via Homebrew on macOS or manual download).fixInstall the Allure Report CLI tool (e.g., `brew install allure` or follow official installation guides: `https://allurereport.org/docs/gettingstarted-installation/`).
affects: All versions
gotchaWhen running Behave tests in parallel (e.g., with `behave-parallel` or `behavex`), using the formatter directly (`-f allure_behave.formatter:AllureFormatter`) might be incompatible or lead to missing features.fixFor parallel execution, it's often necessary to integrate Allure Behave via `environment.py` hooks, calling `from allure_behave.hooks import allure_report` and then `allure_report('path/to/result/dir')` in appropriate `before_all` or `after_all` hooks. Consult `behavex` documentation for its specific Allure integration details. affects: All versions
gotchaThe error `format=allure_behave.formatter:AllureFormatter is unknown` typically indicates that `allure-behave` is not correctly installed or not accessible in the Python environment where `behave` is being run.fixEnsure `pip install allure-behave` has been successfully executed in the active Python environment. Verify the package is listed by `pip list`.
affects: All versions
gotchaUsing `AllureFormatter.hide_excluded=true` with tag-excluded scenarios can lead to steps from the excluded scenarios incorrectly bleeding into the results of the next matching scenario.fixAs a workaround, avoid using `hide_excluded=true` or carefully inspect reports for incorrect step counts if this option is enabled. Check for official bug fixes in newer releases.
affects: 2.15.3 (and potentially earlier/later until fixed)
breakingOlder versions (pre-2.14.2) could produce `AttributeError` if `Allure Behave` was set up via `AllureHooks` or generate extra test results after consecutive in-process runs of `Behave`.fixUpgrade to `allure-behave` 2.14.2 or newer to resolve these specific issues.
affects: <2.14.2
Errors
Common errors & fixes
allure-behave : The term 'allure-behave' is not recognized as the name of a cmdlet, function, script file, or operable program.
The Allure Commandline tool is not installed or not added to the system's PATH.
fixInstall the Allure Commandline tool and ensure it's added to the system's PATH. Refer to the installation instructions at https://allurereport.org/docs/gettingstarted-installation/.
ModuleNotFoundError: No module named 'allure.constants'; 'allure' is not a package
The 'allure.constants' module has been deprecated or removed in newer versions of the Allure Python library.
fixReplace 'from allure.constants import AttachmentType' with 'from allure_commons.types import AttachmentType'.
AttributeError: module 'allure' has no attribute 'attachment_type'
The 'attachment_type' attribute is not present in the 'allure' module.
fixUse 'from allure_commons.types import AttachmentType' and reference attachment types as 'AttachmentType.PNG'.
AttributeError: module 'allure' has no attribute 'severity_level'
The 'severity_level' attribute is not present in the 'allure' module.
fixEnsure that the 'allure-pytest' package is installed instead of 'pytest-allure-adaptor'. Uninstall 'pytest-allure-adaptor' and install 'allure-pytest' using pip.
ModuleNotFoundError: No module named 'frontend'
The 'frontend' module is not found, possibly due to incorrect module imports or missing files.
fixVerify the module's existence and ensure correct import statements. Check the project structure and module paths.
Upgrade
Version history
2.16.0latest on PyPI · released Apr 27, 2026
Audit
Dependencies
behaverequiredRequired for writing and executing BDD tests.
allure-commonsrequiredProvides core Allure API for Python integrations (installed transitively).