Environment Variables

All addresses on this page apply to libtpu.so from the libtpu-0.0.40-cp314 wheel (build libtpu_lts_20260413_b_RC00, build-id md5 89edbbe81c5b328a958fe628a9f2207d, 781,691,048 bytes, ELF x86-64 DYN, not stripped; demangled C++ symbols quoted verbatim). Other versions differ.

Abstract

libtpu reads its configuration from two sources that look the same from a shell but are wired completely differently inside the .so. The first is a small, fixed set of environment variables that the TPU code reads directly through getenv("LITERAL_NAME") — these are the variables a reimplementer must hard-code, because the name string is baked into a specific reader function and there is no registry behind them. The second, and far larger, surface is the absl/XLA flag machinery: XLA_FLAGS, TF_XLA_FLAGS, and the --xla_* / --tpu_* flags injected through LIBTPU_INIT_ARGS are not read by getenv at all — they are parsed once at bootstrap by ParseCommandLineNonHelpFlags against the absl flag tables the dlopen constructor storm pre-registered. This page owns the direct-getenv catalog: every literal env-var name the binary passes to getenv, the function that reads it, and what the value does. The flag surface and its injection channel live elsewhere (see the cross-references).

The decisive fact for a reimplementer is the line between the two. A grep of .rodata finds hundreds of TPU_*, MEGASCALE_*, GRPC_*, and TF_* strings, but most are not env-var reads: TPU_CORE_TYPE_*, TPU_SEQUENCER_TYPE_*, and similar are enum-name strings; TPU_VISIBLE_DEVICES, TPU_HOST_BOUNDS, and TPU_SKIP_MDS_QUERY are absl flag names, bound by the flag parser, not by getenv; the MEGASCALE_* and GRPC_* families are flag/option strings consumed by the distributed-runtime and gRPC layers respectively. Only ~205 distinct strings reach a literal getenv() in the decompiled corpus, and of those only a handful are TPU-specific; the rest are inherited from vendored libraries (hwloc, libpfm, gRPC, GCS, the Google base/ init runtime, absl test harness). The catalog below separates the TPU-owned direct reads (CONFIRMED reader + address) from the flag-bound names (CONFIRMED string, parsed not getenv'd) so a reimplementer knows which to implement as getenv and which to implement as a flag.

A note on secure_getenv: despite the dispatch hardening elsewhere in the runtime, no literal-argument secure_getenv("NAME") call survives in the decompiled corpus — every confirmed env read is plain getenv. The bootstrap is not running with elevated privileges by the time it parses its environment, so the runtime does not bother to drop env access for setuid contexts.

How to Read This Catalog

Each row carries a Reader (the function and address that consumes the variable) and a Confidence that means a specific thing here:

• CONFIRMED — the binary contains a literal getenv("NAME") (or the flag string for a flag-bound row) inside the cited function. The reimplementer should reproduce this exactly.
• HIGH — the env-var string is present and its consuming subsystem is identified, but the precise reader call was inferred from the surrounding function rather than pinned to a single getenv line.
• LOW — the string is present but whether it is read (vs. defined as a flag name, an enum name, or a value emitted into a log) was not resolved.

GOTCHA — a string in .rodata is not evidence of an env-var read. The single most common reimplementation error here is treating an absl flag name (e.g. TPU_VISIBLE_DEVICES) as a getenv target. libtpu binds those through the flag parser; calling getenv("TPU_VISIBLE_DEVICES") in a reimplementation would read a variable libtpu never reads. The catalog marks every flag-bound name explicitly.

1. Flag Injection

The primary configuration channel. A plugin .so has no command line of its own, so libtpu fabricates one from LIBTPU_INIT_ARGS and feeds it to the absl flag parser. The mechanics of the ingest — the space split, the argv[0] synthesis, the vector<string> → char** flatten — are documented in full on ../lifecycle/tftpu-initialize-bootstrap.md §2; the flags that string carries are catalogued on xla-flag-atlas.md. This page records only the env-var reads themselves.

NOTE — LIBTPU_INIT_ARGS is the only TPU-specific variable in this group read by a literal getenv. XLA_FLAGS / TF_XLA_FLAGS are read by the generic absl flag-from-env code (absl::ParseCommandLine reads them by way of ABSL_FLAGS_FROM_ENV-style scanning), so they are environment variables in effect but are not getenv'd at any TPU call site. A reimplementer must wire all three into one flag parse, but only LIBTPU_INIT_ARGS is a hand-rolled getenv in the TPU layer.

2. Device Selection and Topology

These variables describe the slice geometry the process should see. The split here is sharp and easy to get wrong: the bounds variables are read directly by getenv inside the lock gate, while the visible-device selectors are absl flag names.

Direct getenv reads

Flag-bound names (NOT getenv'd)

QUIRK — there are two host-bounds knobs with different plumbing. TPU_CHIPS_PER_HOST_BOUNDS is a real getenv read inside TryAcquireTpuLock; TPU_HOST_BOUNDS is a flag name parsed by absl. They overlap in meaning but reach the runtime by different paths — a reimplementer must reproduce the first as getenv and the second as a flag, or one of the two will silently do nothing.

3. Runtime Mode and Buffer Tuning

Direct getenv reads that select the runtime backend and tune transfer buffers.

4. Distributed / Megascale and Coordination

The multi-slice (Megascale) layer is configured almost entirely by flag-bound MEGASCALE_* strings, not by getenv. The one direct getenv in the Megascale path is the bypass switch in §3 (SKIP_MEGASCALE_PJRT_CLIENT). The coordination/topology exchange that consumes these is documented on ../megascale/bootstrap/overview.md.

NOTE — the MEGASCALE_* family is consumed by the multi-slice runtime through its options/flag parsing rather than discrete getenv calls, which is why none appear in the literal-getenv set even though all ten strings are present in .rodata. The bypass (SKIP_MEGASCALE_PJRT_CLIENT) is the exception: it is a genuine getenv inside PJRT_Client_Create, because it must short-circuit before any Megascale option parsing happens.

5. Profiling, Dump, and Telemetry

A mix of direct getenv reads (telemetry platform labels, TF graph dumps) and flag-bound dump directives. The XLA_FLAGS-driven HLO dump knobs (--xla_dump_to, etc.) are not env vars — they are flags carried through the LIBTPU_INIT_ARGS channel (see xla-flag-atlas.md).

6. Inherited (Non-TPU) Environment

libtpu statically links a large stack of Google and third-party libraries, each of which reads its own environment. These are present and functional in the loaded .so but are not part of the TPU configuration surface a reimplementer of the TPU runtime needs to reproduce. They are catalogued by family rather than enumerated, because the list runs to ~180 distinct strings and reproducing them is reproducing those libraries, not libtpu.

NOTE — XLA_ALLOW_GET_DEFAULT_PLATFORM is a genuine literal getenv read (in the XLA platform-manager layer), but it gates XLA's default-platform fallback, not anything TPU-specific. It is listed here rather than in §2 because a TPU-only reimplementation never reaches the code that consults it.

7. The TPU_LIBRARY_PATH Special Case

TPU_LIBRARY_PATH is the one variable users most associate with libtpu, yet libtpu.so itself does not getenv it. The wheel's Python wrapper sets it:

# libtpu/__init__.py (from the wheel)
if not os.environ.get('TPU_LIBRARY_PATH'):
    os.environ['TPU_LIBRARY_PATH'] = get_library_path()   # path to this libtpu.so

The variable is then read by the framework loader (JAX/PJRT's plugin-discovery code in the host process) to locate the .so to dlopen. By the time libtpu's own code runs, the path has already done its job. A reimplementer of libtpu does not implement TPU_LIBRARY_PATH; a reimplementer of the plugin loader does. The two confirmed string references to TPU_LIBRARY_PATH in the report are this Python assignment and read, not a getenv inside the binary.

QUIRK — the wheel ships TPU_LIBRARY_PATH as a set-if-unset in __init__.py, so importing libtpu is what wires the framework to the bundled .so. Setting TPU_LIBRARY_PATH in the environment before import overrides which libtpu.so is loaded — the bundled __init__.py honors a pre-existing value. This is the override hook for pointing JAX at a custom libtpu build.

Cross-References

• overview.md — the configuration-surface map: flags, knobs, the compilation environment, and where env vars sit among them
• ../lifecycle/tftpu-initialize-bootstrap.md — the LIBTPU_INIT_ARGS ingest mechanics (space split, argv[0] synthesis, the flag parse) and the TPU_LOAD_LIBRARY lock gate
• xla-flag-atlas.md — the --xla_* / --tpu_* flags that LIBTPU_INIT_ARGS and XLA_FLAGS actually inject
• flag-families.md — how the flag names are grouped and prefix-dispatched once parsed
• ../megascale/bootstrap/overview.md — the multi-slice bootstrap that consumes the MEGASCALE_* options and is gated by SKIP_MEGASCALE_PJRT_CLIENT