{"id":794,"library":"pbr","title":"Python Build Reasonableness (PBR)","description":"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.","status":"active","version":"7.0.3","language":"python","source_language":"en","source_url":"https://github.com/openstack/pbr","tags":["packaging","setuptools","openstack","build-system","versioning","automation"],"install":[{"cmd":"pip install pbr","lang":"bash","label":"Install PBR"}],"dependencies":[{"reason":"PBR is a setuptools plugin and builds on its functionality for packaging.","package":"setuptools","optional":false},{"reason":"Required for automatic versioning, AUTHORS, and ChangeLog generation.","package":"git","optional":false},{"reason":"Required for building wheel distributions, especially with PEP 517/518 build systems.","package":"wheel","optional":true}],"imports":[{"note":"PBR is primarily configured via setup.cfg and pyproject.toml, with a minimal setup.py calling setuptools.setup().","symbol":"setup","correct":"from setuptools import setup"},{"note":"The version information is typically accessed via the pbr.version module's VersionInfo class, not a direct import of 'version' from 'pbr'.","wrong":"from pbr import version","symbol":"VersionInfo","correct":"import pbr.version; version = pbr.version.VersionInfo('my_package').version_string()"}],"quickstart":{"code":"import setuptools\n\n# setup.py\nsetuptools.setup(\n    setup_requires=['pbr>=2.0.0'],\n    pbr=True,\n)\n\n# --- setup.cfg ---\n# [metadata]\n# name = my-package\n# author = Your Name\n# author-email = your@email.com\n# summary = A short summary of my package\n# description-file = README.rst\n# license = MIT\n# classifier =\n#     Development Status :: 4 - Beta\n#     Programming Language :: Python\n# keywords = example, packaging\n# \n# [files]\n# packages = my_package\n# \n# [entry_points]\n# console_scripts =\n#     my-command = my_package.cli:main\n# \n# --- pyproject.toml (for modern projects) ---\n# [build-system]\n# requires = [\"pbr>=7.0.0\", \"setuptools>=61.0.0\", \"wheel\"]\n# build-backend = \"pbr.build\"\n","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=1.10.0 (and possibly others up to ~2.0)"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions, but particularly important for migrations to newer Python versions or build backends."},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'7.0.3':79 'activ':82 'aim':62 'author':43 'autom':29,97 'automat':56 'base':25,37 'behavior':21 'build':2,7,74,94 'build-system':93 'cadenc':84 'changelog':45 'common':30 'configur':69 'consist':71 'current':76 'cycl':89 'default':20 'depend':51 'descript':58 'develop':12,88 'file':46,54 'generat':41 'git':39,48 'handl':50 'histori':49 'inject':16 'librari':11 'long':57 'manag':36 'openstack':14,87,92 'packag':31,90 'pbr':4,5 'project':27 'python':1,6,26 'readm':60 'reason':3,8 'releas':83 'repeat':73 'requir':53 'sensibl':19 'setup.cfg':68 'setup.py':66 'setuptool':24,91 'setuptools-bas':23 'simplifi':64 'system':95 'tag':40 'task':32 'tie':85 'use':17 'version':35,77,96 'via':52","created_at":"2026-03-29T04:21:59.243858+00:00","updated_at":"2026-04-16T17:56:00.512647+00:00","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'pbr'"},{"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.","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.","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."},{"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`.","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.","error":"AttributeError: 'NoneType' object has no attribute 'get_script_header'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"7.0.3","cli_name":"pbr","cli_version":"7.0.3","type":"library","homepage":"https://docs.openstack.org/pbr/latest/","github":null,"docs":"https://docs.openstack.org/pbr/","changelog":null,"pypi":"https://pypi.org/project/pbr/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}