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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.048s · 17.8MB
glibcpy 3.10–3.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.fixAlways 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')`.fixReview 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.fixUpdate 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`.fixIf 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.