{"id":1398,"library":"bazel-runfiles","title":"Bazel Runfiles","description":"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.","status":"active","version":"1.9.0","language":"en","source_language":"en","source_url":"https://github.com/bazel-contrib/rules_python","tags":["bazel","build system","runfiles","python development","rules_python"],"install":[{"cmd":"pip install bazel-runfiles","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary functionality is exposed via the 'runfiles' submodule, not directly from the top-level package.","wrong":"import bazel_runfiles","symbol":"runfiles","correct":"from bazel_runfiles import runfiles"}],"quickstart":{"code":"import os\nfrom bazel_runfiles import runfiles\n\n# When run via 'bazel run', Bazel automatically sets the necessary\n# environment variables (BAZEL_RUNFILES_MANIFEST_FILE or BAZEL_RUNFILES_DIR).\n# For local testing or non-Bazel execution, you might need to set them manually\n# or use a different 'Create' method, but this is uncommon for typical usage.\n\ntry:\n    # Create a Runfiles object. This will automatically detect the appropriate\n    # manifest or directory based on environment variables set by Bazel.\n    r = runfiles.Create()\n\n    # Example: Locate a data file included in your Bazel BUILD rule.\n    # Assume a BUILD target like:\n    # py_binary(\n    #     name = \"my_app\",\n    #     srcs = [\"my_app.py\"],\n    #     data = [\"//path/to/my:data.txt\"],\n    # )\n    # The path here is relative to your workspace root, e.g., 'path/to/my/data.txt'\n    data_file_path = r.Rlocation('path/to/my/data.txt')\n\n    if data_file_path:\n        print(f\"Located data file at: {data_file_path}\")\n        if os.path.exists(data_file_path):\n            with open(data_file_path, 'r') as f:\n                content = f.read()\n            print(f\"Content of data.txt: {content[:50]}...\")\n        else:\n            print(\"Warning: File path resolved but file does not exist. (Perhaps no such data file was configured for this target?)\")\n    else:\n        print(\"Could not locate 'path/to/my/data.txt'. Ensure it's correctly added to a 'data' attribute in your BUILD file.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"This might happen if not executed in a Bazel runfiles environment.\")\n    print(\"Ensure BAZEL_RUNFILES_MANIFEST_FILE or BAZEL_RUNFILES_DIR is set.\")\n\n# You can also resolve the path of the current executable itself\n# Note: CurrentExecutable() requires a special setup for the symlink to be resolvable directly.\n# executable_path = r.Rlocation(r.CurrentExecutable())\n# print(f\"Current executable path in runfiles: {executable_path}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"Paths 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')`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Prior 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.","severity":"breaking","affected_versions":"<=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)."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}