bazel-runfiles library

This is a Bazel Runfiles lookup library for Bazel-built Python binaries and tests.

Learn about runfiles: read Runfiles guide or watch Fabian's BazelCon talk.

Importing

The Runfiles API is available from two sources, a direct Bazel target, and a pypi package.

Pure Bazel imports

1. Depend on this runfiles library from your build rule, like you would other third-party libraries:

   py_binary(
       name = "my_binary",
       # ...
       deps = ["@rules_python//python/runfiles"],
   )
   

2. Import the runfiles library:

       from python.runfiles import Runfiles
   

Pypi imports

1. Add the 'bazel-runfiles' dependency along with other third-party dependencies, for example in your requirements.txt file.

2. Depend on this runfiles library from your build rule, like you would other third-party libraries:

   load("@pip_deps//:requirements.bzl", "requirement")
   
   py_binary(
       name = "my_binary",
       ...
       deps = [requirement("bazel-runfiles")],
   )
   

3. Import the runfiles library:

   from runfiles import Runfiles
   

Typical Usage

Create a Runfiles object and use Rlocation to look up runfile paths:

r = Runfiles.Create()
# ...
with open(r.Rlocation("my_workspace/path/to/my/data.txt"), "r") as f:
    contents = f.readlines()
    # ...

Here my_workspace is the name you specified via module(name = "...") in your MODULE.bazel file (with --enable_bzlmod, default as of Bazel 7) or workspace(name = "...") in WORKSPACE (with --noenable_bzlmod).

The code above creates a manifest- or directory-based implementation based on the environment variables in os.environ. See Runfiles.Create() for more info.

Alternatively, Runfiles.CreateOrRaise() can be used to raise an error instead of returning None if runfiles cannot be found:

r = Runfiles.CreateOrRaise()

If you want to explicitly create a manifest- or directory-based implementation, you can do so as follows:

r1 = Runfiles.CreateManifestBased("path/to/foo.runfiles_manifest")

r2 = Runfiles.CreateDirectoryBased("path/to/foo.runfiles/")

If you want to start subprocesses that access runfiles, you have to set the right environment variables for them:

import subprocess
from python.runfiles import Runfiles

r = Runfiles.Create()
env = {}
# ...
env.update(r.EnvVars())
p = subprocess.run(
    [r.Rlocation("path/to/binary")],
    env=env,
    # ...
)