bazel-runfiles

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

• 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"],
  )
  

• Import the runfiles library:

      from python.runfiles import Runfiles
  

Pypi imports

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

• 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")],
  )
  

• 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.

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,
    # ...
)