Installation

Behave is distributed as a standard Python package named behave. It supports Python 3 and installs with pip together with its core dependencies, including parse and parse_type for step matching and `six`-free Python 3 internals. No compiler or system library is required, so installation works on Windows, macOS, and Linux.

Installing with pip

The recommended way to install behave is inside a virtual environment so the project's dependencies stay isolated from the system Python:

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install behave

Verify the installation by asking behave for its version. This also confirms that the command-line entry point is on your PATH:

behave --version
python -m behave --version

Both commands print a version string such as 1.2.6. If the behave command is not found but the module command works, your virtual environment's bin directory is not on the PATH, which is common when running from IDEs; invoke behave through python -m behave instead.

Pinning the Version

For reproducible builds, pin behave in the project's requirements file. A common setup keeps test dependencies separate from runtime dependencies:

pip install "behave==1.2.6"
pip freeze | grep behave >> requirements-test.txt

Continuous integration systems should install from the pinned file so local and CI runs use identical versions, avoiding surprises when a new behave release changes output formatting or step matching details.

Project Layout

After installation, behave needs a working directory structure. The minimal layout that behave recognizes without extra configuration is:

myproject/
    features/
        example.feature
        steps/
            example_steps.py
        environment.py

Behave searches for .feature files under features/ by default. Step definitions must live in a steps subdirectory so they are imported after parsing but before execution. The optional environment.py file is auto-discovered in the feature directory and provides the hook functions used for setup and teardown.

Verifying the Setup

Create a tiny feature and run behave to confirm everything works end to end:

Feature: smoke test
  Scenario: behave runs correctly
    Given behave is installed
    Then no error occurs

from behave import given, then

@given("behave is installed")
def step_impl(context):
    pass

@then("no error occurs")
def step_impl(context):
    pass

behave

A successful run prints one scenario, three steps, and statistics line 1 feature passed, 1 scenario passed. If instead you see undefined steps, behave found the feature file but not the step module — check that the steps directory is nested inside the feature directory.

Common Issues

• Multiple Python versions: pip may install into a different interpreter than the one running behave; use python -m pip install behave with the intended interpreter.
• Corporate proxies: set HTTPS_PROXY or use pip install --index-url with an internal mirror.
• Editable installs: for contributing or customizing, install behave from a cloned Git repository with pip install -e ..

Summary

Install behave with pip inside a virtual environment, pin the version in requirements, lay out the features/ directory with a steps/ subfolder, and verify with a smoke test feature. With these pieces in place you are ready to write and run your first real scenarios.