Registry / devops / bazel-runfiles

bazel-runfiles

JSON →
library2.3.2pypypi✓ verified 25d ago

The `bazel-runfiles` library provides utilities to locate and access data files bundled as Bazel 'runfiles' within a Python binary or test. It is part of the `rules_python` ecosystem, currently at version 1.9.0, and receives updates aligned with `rules_python` releases, which are fairly regular.

pip install bazel-runfiles
INSTALL
IMPORT
SIG · BAZEL-RUNFILES
B
bazel-runfiles
devopspythonv2.3.2
Install
1.6s avg
Import
45ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.3.2 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.048s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.042s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Runfiles
from runfiles import Runfiles
from bazel_runfiles import runfiles
Create
from runfiles import Create
CreateManifestBased
from runfiles import CreateManifestBased

This quickstart demonstrates how to initialize the `runfiles` resolver and locate a data file. For this code to function correctly, it must be executed within a Bazel build context (e.g., using `bazel run //path/to:my_app`) or with the `BAZEL_RUNFILES_MANIFEST_FILE` or `BAZEL_RUNFILES_DIR` environment variables manually set.

import os from bazel_runfiles import runfiles # When run via 'bazel run', Bazel automatically sets the necessary # environment variables (BAZEL_RUNFILES_MANIFEST_FILE or BAZEL_RUNFILES_DIR). # For local testing or non-Bazel execution, you might need to set them manually # or use a different 'Create' method, but this is uncommon for typical usage. try: # Create a Runfiles object. This will automatically detect the appropriate # manifest or directory based on environment variables set by Bazel. r = runfiles.Create() # Example: Locate a data file included in your Bazel BUILD rule. # Assume a BUILD target like: # py_binary( # name = "my_app", # srcs = ["my_app.py"], # data = ["//path/to/my:data.txt"], # ) # The path here is relative to your workspace root, e.g., 'path/to/my/data.txt' data_file_path = r.Rlocation('path/to/my/data.txt') if data_file_path: print(f"Located data file at: {data_file_path}") if os.path.exists(data_file_path): with open(data_file_path, 'r') as f: content = f.read() print(f"Content of data.txt: {content[:50]}...") else: print("Warning: File path resolved but file does not exist. (Perhaps no such data file was configured for this target?)") else: print("Could not locate 'path/to/my/data.txt'. Ensure it's correctly added to a 'data' attribute in your BUILD file.") except Exception as e: print(f"An error occurred: {e}") print("This might happen if not executed in a Bazel runfiles environment.") print("Ensure BAZEL_RUNFILES_MANIFEST_FILE or BAZEL_RUNFILES_DIR is set.") # You can also resolve the path of the current executable itself # Note: CurrentExecutable() requires a special setup for the symlink to be resolvable directly. # executable_path = r.Rlocation(r.CurrentExecutable()) # print(f"Current executable path in runfiles: {executable_path}")
Debug
Known issues
gotchaThe `bazel-runfiles` library is designed to operate within a Bazel build environment. It relies on environment variables (`BAZEL_RUNFILES_MANIFEST_FILE` or `BAZEL_RUNFILES_DIR`) set by Bazel during execution. Running scripts directly with `python` outside of a `bazel run` or `bazel test` context will likely result in `FileNotFoundError` or `ValueError` if these variables are not manually provided.
fix
Always execute your Python programs using `bazel run //path/to:target` or `bazel test //path/to:target`. If manual execution is required (e.g., for debugging), ensure the `BAZEL_RUNFILES_MANIFEST_FILE` or `BAZEL_RUNFILES_DIR` environment variables are correctly set, typically pointing to the manifest file or runfiles directory generated by Bazel.
affects: All versions
gotchaPaths provided to `Rlocation()` must be relative to the Bazel workspace root, not relative to the Python source file. For example, if `data.txt` is at `my_package/data.txt` in your workspace, and you add it to a `data` attribute in a `BUILD` file, you would request `r.Rlocation('my_package/data.txt')`.
fix
Review your `BUILD` file's `data` attribute for the target and ensure the path passed to `Rlocation()` exactly matches the runfiles path (typically the path from the workspace root).
affects: All versions
breakingPrior to `bazel-runfiles` becoming the standard, `rules_python` used alternative methods for accessing data files (e.g., direct imports from generated `py_path.runfiles`). Migrating older Bazel Python projects to recent `rules_python` versions often requires updating runfiles access to use the `bazel_runfiles.runfiles.Create().Rlocation()` pattern.
fix
Update your code to import `from bazel_runfiles import runfiles` and use `runfiles.Create().Rlocation(...)` for accessing data files. Consult the `rules_python` changelog and documentation for specific migration guides if upgrading from a very old setup.
affects: <=1.x.x (older rules_python versions), specifically before `bazel-runfiles` was standardized as the main API (circa `rules_python` 0.x - 1.x transition).
breakingThe `ModuleNotFoundError: No module named 'bazel_runfiles'` indicates that the `bazel_runfiles` library is not installed or available in the Python environment where the script is being executed. While Bazel typically handles dependencies for its targets, running Python scripts directly outside a Bazel context requires explicit installation of `bazel-runfiles`.
fix
If running outside a Bazel build, install the library using `pip install bazel-runfiles`. If running within Bazel, ensure your `py_library` or `py_binary` target correctly declares `bazel_runfiles` as a dependency (e.g., `deps = ['@bazel_tools//tools/python/runfiles:runfiles_lib']`).
affects: All versions
Upgrade
Version history
2.3.2latest on PyPI · released Aug 22, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
23 hits · last 30 days
node
22
Resources
bazel-runfiles — pip install bazel-runfiles · libregistry