Install & Compatibility
Where this runs
tested against v2.0.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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 70.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.4s · import 0.000s · 71MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DjangoBehaveTestCase
✓ from behave_django.test_case import DjangoBehaveTestCase
✗ from behave_django.test_case import DjangoBehaveTestCase
To get started, define your `features/` directory with `.feature` files and corresponding step definitions in `features/steps/`. Behave-Django automatically detects these. An `environment.py` file is typically used for setup/teardown hooks (e.g., `before_all`, `after_scenario`). Ensure your Django settings are configured correctly for testing. You can run `behave` from your Django project root.
from django.test import TestCase
class MyFeatureTests(TestCase):
def test_example_scenario(self):
# Your Django-specific test logic here
self.assertEqual(1 + 1, 2)
# features/example.feature
# Feature: Example Feature
# Scenario: Basic addition
# Given I have the number 1
# And I add the number 1
# Then the result should be 2
# features/steps/example_steps.py
# from behave import given, when, then
# from django.test import TestCase
# from behave_django.decorators import fixtures
# @fixtures(['my_fixture.json'])
# @given('I have the number {number:d}')
# def step_impl(context, number):
# context.a = number
# @when('I add the number {number:d}')
# def step_impl(context, number):
# context.result = context.a + number
# @then('the result should be {expected_result:d}')
# def step_impl(context, expected_result):
# assert context.result == expected_result
behave --version
Debug
Known issues
breakingThe `--runner-class` option was renamed to `--runner` in behave-django 1.5.0, and it now requires `parent.module:class` syntax.fixUpdate command-line invocations. For example, change `--runner-class my_runner` to `--runner my_module:MyRunnerClass`.
affects: >=1.5.0
breakingPython 3.6, 3.7, Django 3.3, and 4.1 support was dropped in behave-django 1.5.0. Python 3.8 support was dropped in 1.6.0. Python 3.9 is now the minimum required. Django 5.2+ requires specific fixes in 1.6.0 and 1.9.0.fixUpgrade your Python environment to 3.9+ and Django to a supported version (e.g., Django 4.2+, 5.x). Check the release notes for specific version requirements.
affects: >=1.5.0
gotchaAutomatic fixture resetting is planned for v2.0.0. In current versions, if `fixtures` are set to an empty list, they might not reset correctly, especially on Django 5.2+. This was fixed in 1.9.0 for the empty list case.fixFor versions prior to 1.9.0, or to be safe before 2.0.0's automatic reset, manually manage fixture cleanup in your `after_scenario` hooks if you encounter issues with fixture state persistence.
affects: <2.0.0 (especially Django 5.2+)
gotchaOlder versions of behave-django (before 1.8.0) experienced issues with database transaction rollback due to incompatibilities with Behave 1.2.7.dev8 and later.fixUpgrade to behave-django 1.8.0 or newer to ensure proper database transaction handling and rollback. This version depends on behave 1.3.3+.
affects: <1.8.0
Upgrade
Version history
2.0.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
behaverequiredCore BDD framework integration; requires behave 1.3.3+ as of behave-django 1.8.0.
DjangorequiredThe web framework being integrated with Behave; requires Django >=3.2.