Python Build Reasonableness (PBR)

7.0.3 verified Tue May 12 auth: no python install: verified quickstart: stale

PBR (Python Build Reasonableness) is a library developed by OpenStack that injects useful and sensible default behaviors into setuptools-based Python projects. It automates common packaging tasks such as version management based on Git tags, generation of AUTHORS and ChangeLog files from Git history, handling dependencies via requirements files, and automatic long descriptions from READMEs. It aims to simplify the `setup.py` and `setup.cfg` configuration for consistent and repeatable builds. The current version is 7.0.3, with an active release cadence tied to OpenStack development cycles.

pip install pbr

Common errors

error ModuleNotFoundError: No module named 'pbr' ↓

cause The 'pbr' package is not installed in the Python environment being used, or there is a mismatch between the Python interpreter used for installation and the one running the application.

fix

Ensure pbr is installed in the correct environment using pip install pbr or pip3 install pbr. If using a virtual environment, activate it before installing.

error Exception: Versioning for this project requires either an sdist tarball, or access to an upstream git repository. It's also possible that there is a mismatch between the package name in setup.cfg and the argument given to pbr.version.VersionInfo. Project name <project_name> was given, but was not able to be found. ↓

cause PBR relies on Git metadata (tags, commits) to determine the package version. This error occurs when installing from a source distribution without Git information (e.g., a downloaded .zip file from GitHub), or if Git tags are not properly set/signed, or if the project name in `setup.cfg` does not match the expected package name.

fix

When developing, clone the repository using git clone instead of downloading a zip. Ensure Git tags are correctly formatted and preferably signed (git tag -s v1.0.0). For distribution, create a source distribution (python setup.py sdist) from a Git-enabled directory before packaging.

error AttributeError: 'NoneType' object has no attribute 'get_script_header' ↓

cause This error typically arises during `setup.py` execution within a pbr-managed project, often due to an outdated or conflicting version of setuptools, or an issue where pbr's internal machinery (like `easy_install`) cannot be properly initialized or accessed.

fix

Upgrade setuptools to the latest version (pip install --upgrade setuptools). If the issue persists, ensure all direct and transitive dependencies are compatible and consider running pip install pbr --upgrade.

Warnings

breaking PBR 7.0.0 introduced significant breaking changes, deprecating or removing many options from `setup.cfg` sections like `[backwards_compat]`, `[metadata]`, `[files]`, and `[entry_points]`. The `tests_require` option was also deprecated. ↓

fix Review the official PBR 7.0.0 release notes and documentation for updated configuration options. Migrate deprecated `setup.cfg` options to their new locations or equivalent `pyproject.toml` configurations. For example, `[files]` and `[entry_points]` sections should be moved to `[options]` or `[tools.setuptools]` in `setup.cfg` or `pyproject.toml` respectively.

deprecated PBR has deprecated support for `pyN`-suffixed requirement files in favor of environment markers. Additionally, `testr` and `nose` integration for `setup.py test` has been deprecated. ↓

fix Update requirement files to use PEP 508 environment markers. For testing, use `testr` or `nose` directly with their native setuptools commands instead of relying on PBR's integration.

gotcha PBR heavily relies on Git for versioning, AUTHORS, and ChangeLog generation. If your project is not a Git repository, or if Git is not installed/accessible, these features will not work as expected and may result in default versions (e.g., '0.0.1') or build failures. ↓

fix Ensure your project is a Git repository and that Git is installed and accessible in the build environment. For production releases, it's recommended to create a Git tag to explicitly define the version.

gotcha Older versions of PBR (e.g., 0.11.0, 1.10.0) had known issues causing `ImportError: No module named pbr.pbr_json` or `ModuleNotFoundError: No module named 'testrepository'` during `pip install` of packages that depend on them. This often occurred when `pbr` was not installed or was an outdated version before its dependencies. ↓

fix Ensure `pbr` is explicitly listed as a `setup_requires` dependency in `setup.py` (e.g., `setup_requires=['pbr>=2.0.0']`) and/or update `pyproject.toml` to specify a sufficiently recent version (`pbr>=7.0.0`). Uninstalling and reinstalling `pbr` or clearing problematic `site-packages` entries might also be necessary.

deprecated PBR 7.0.2 removed remaining uses of `pkg_resources` internally, moving towards `importlib.metadata` and `packaging` for better Python 3 compatibility and modern practices. ↓

fix While this is an internal change, it's a good practice for downstream projects to also avoid direct `pkg_resources` usage where possible, especially in `setup.py` scripts that PBR interacts with.

breaking PBR requires a `setup.cfg` file in the project's root directory for configuration. If `setup.cfg` is missing, PBR will raise a `DistutilsFileError`, leading to a build failure. ↓

fix Ensure a `setup.cfg` file exists in the project root directory. It should contain at least a `[metadata]` section and a `[pbr]` section with `autodoc_index_modules = True` or `skip_authors = True` and `skip_changelog = True` if not using those features.

gotcha When `pbr=True` is specified in `setup.py`, PBR expects a `setup.cfg` file to exist in the project root for configuration and metadata extraction. Its absence will result in a `distutils.errors.DistutilsFileError`. ↓

fix Ensure a `setup.cfg` file is present in your project's root directory when `pbr=True` is used in `setup.py`. Even if it's minimal (e.g., an empty file or just a `[metadata]` section), it must exist.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.76s 19.7M

3.10 alpine (musl) - - 0.81s 19.7M

3.10 slim (glibc) wheel 1.5s 0.55s 20M

3.10 slim (glibc) - - 0.58s 20M

3.11 alpine (musl) wheel - 1.02s 22.0M

3.11 alpine (musl) - - 1.12s 22.0M

3.11 slim (glibc) wheel 1.7s 0.85s 23M

3.11 slim (glibc) - - 0.83s 23M

3.12 alpine (musl) wheel - 0.50s 21.4M

3.12 alpine (musl) - - 0.52s 21.4M

3.12 slim (glibc) wheel 2.2s 0.51s 22M

3.12 slim (glibc) - - 0.49s 22M

3.13 alpine (musl) wheel - 0.48s 21.2M

3.13 alpine (musl) - - 0.48s 21.1M

3.13 slim (glibc) wheel 2.2s 0.47s 22M

3.13 slim (glibc) - - 0.48s 22M

3.9 alpine (musl) wheel - 0.88s 19.3M

3.9 alpine (musl) - - 0.86s 19.3M

3.9 slim (glibc) wheel 1.8s 0.66s 20M

3.9 slim (glibc) - - 0.70s 20M

Imports

setup
```
from setuptools import setup
```
PBR is primarily configured via setup.cfg and pyproject.toml, with a minimal setup.py calling setuptools.setup().
VersionInfo
wrong
```
from pbr import version
```
correct
```
import pbr.version; version = pbr.version.VersionInfo('my_package').version_string()
```
The version information is typically accessed via the pbr.version module's VersionInfo class, not a direct import of 'version' from 'pbr'.

Quickstart stale last tested: 2026-04-24

To use PBR, you need a minimal `setup.py` file that calls `setuptools.setup()` and sets `pbr=True`. Most of your project metadata and configuration (e.g., name, dependencies, entry points, versioning strategy) will reside in `setup.cfg` and, for modern Python packaging, in `pyproject.toml`. PBR then processes these configuration files to provide default behaviors and inject values into `setuptools`.

import setuptools

# setup.py
setuptools.setup(
    setup_requires=['pbr>=2.0.0'],
    pbr=True,
)

# --- setup.cfg ---
# [metadata]
# name = my-package
# author = Your Name
# author-email = your@email.com
# summary = A short summary of my package
# description-file = README.rst
# license = MIT
# classifier =
#     Development Status :: 4 - Beta
#     Programming Language :: Python
# keywords = example, packaging
# 
# [files]
# packages = my_package
# 
# [entry_points]
# console_scripts =
#     my-command = my_package.cli:main
# 
# --- pyproject.toml (for modern projects) ---
# [build-system]
# requires = ["pbr>=7.0.0", "setuptools>=61.0.0", "wheel"]
# build-backend = "pbr.build"