> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nixl/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nixl/_mcp/server.

# Environment Variables

> Complete reference for all NIXL environment variables covering core configuration, etcd, telemetry, and backend-specific settings.

## Overview

NIXL uses environment variables for runtime configuration. This page documents all recognized variables, grouped by subsystem. Environment variables are read at agent initialization time and cannot be changed after an agent is created.

Variables are organized into the following categories:

- **Core** -- Logging and plug-in discovery that apply to all NIXL deployments
- **etcd** -- Distributed metadata exchange configuration
- **Telemetry** -- Performance monitoring, event collection, and export
- **Backend-Specific** -- Transport-level settings for individual backends (UCX, Libfabric, Mooncake, S3, Azure Blob, GDS)

<Note>
Boolean environment variables follow the convention: set to `y`/`yes`/`on`/`true`/`enable`/`1` (case-insensitive) to enable, or `n`/`no`/`off`/`false`/`disable`/`0` to disable. Presence-check variables are activated by setting them to any value.
</Note>

## Core Variables

These variables control fundamental NIXL behavior across all backends.

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NIXL_LOG_LEVEL` | String | `WARN` | Controls log verbosity. Values: `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`. |
| `NIXL_PLUGIN_DIR` | String (path) | System default | Custom directory to search for backend plug-in shared libraries. |
| `NIXL_DISABLE_CUDA_ADDR_WA` | Boolean (presence) | Not set (workaround enabled) | Disables CUDA address workaround in the Libfabric backend. Set this variable to any value to disable the workaround. |

## etcd Variables

These variables configure NIXL's distributed metadata exchange via etcd.

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NIXL_ETCD_ENDPOINTS` | String (URL) | None (etcd disabled) | etcd server endpoint(s). Setting this activates etcd metadata exchange mode. Example: `http://localhost:2379`. |
| `NIXL_ETCD_NAMESPACE` | String (path) | `/nixl/agents/` | Key prefix namespace for agent metadata stored in etcd. |

<Tip>
For detailed etcd setup and usage, see the [Metadata Exchange with etcd](/nixl/user-guide/metadata-exchange-with-etcd) guide.
</Tip>

## Telemetry Variables

These variables control NIXL's built-in telemetry collection and export system.

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NIXL_TELEMETRY_ENABLE` | Boolean | `false` | Enable telemetry collection. Accepts `y`/`yes`/`on`/`true`/`enable`/`1` (case-insensitive) to enable. |
| `NIXL_TELEMETRY_ENABLED_METRICS` | String | None | Optional comma-separated fnmatch allowlist of event names. Unset or empty exports all events. |
| `NIXL_TELEMETRY_BUFFER_SIZE` | Integer | `4096` | Number of events in the cyclic telemetry buffer. Must be a power of 2. |
| `NIXL_TELEMETRY_RUN_INTERVAL` | Integer (ms) | `100` | Flush interval in milliseconds for the telemetry exporter. |
| `NIXL_TELEMETRY_EXPORTER` | String | None | Name of the telemetry exporter plug-in to load (e.g., `prometheus`). |
| `NIXL_TELEMETRY_DIR` | String (path) | None | Directory for shared memory telemetry files used by the cyclic buffer exporter. If telemetry is enabled but this is not set, no telemetry file is generated. |
| `NIXL_TELEMETRY_PROMETHEUS_PORT` | Integer | `9090` | HTTP listen port for the Prometheus telemetry exporter. |
| `NIXL_TELEMETRY_PROMETHEUS_LOCAL` | Boolean | `false` | When `true`, binds the Prometheus exporter to localhost only (`127.0.0.1`) instead of all interfaces (`0.0.0.0`). |

<Tip>
For the full telemetry architecture and usage examples, see the [Telemetry Guide](/nixl/user-guide/telemetry-guide).
</Tip>

## Backend-Specific Variables

### UCX

<Note>
These variables apply when using the UCX transport backend.
</Note>


| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NIXL_UCX_WARNING_TIMEOUT` | Integer (ms) | `5000` | Timeout in milliseconds for UCX memory registration warning. If a memory registration takes longer than this threshold, a warning is logged. |


### Libfabric

<Note>
These variables apply when using the Libfabric transport backend.
</Note>


| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NIXL_LIBFABRIC_MAX_BW_PER_DRAM_SEG` | Integer (Gbps) | Auto-computed from PCIe topology | Bandwidth limit in Gbps for NUMA-aware rail selection on DRAM segments. Override this when the auto-detected PCIe topology does not accurately reflect your network configuration. |

Additional `NIXL_LIBFABRIC_*` variables may exist for provider-specific configuration. The Libfabric backend constructs environment variable names dynamically using the `NIXL_LIBFABRIC_` prefix followed by an uppercase key name. Consult the Libfabric backend README for provider-specific options.


### Mooncake

<Note>
These variables apply when using the Mooncake transport backend.
</Note>


| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NIXL_MOONCAKE_IP_ADDR` | String (IP) | First non-loopback interface IP | Override IP address for the Mooncake transport engine. Set this when auto-detection selects the wrong network interface. |


### S3 / Object Storage

<Note>
These variables apply when using the S3/Object Storage backend.
</Note>


| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `AWS_DEFAULT_BUCKET` | String | None | Default S3 bucket name. Used as fallback when `bucket` is not specified in backend parameters. |
| `AWS_ENDPOINT_OVERRIDE` | String (URL) | None | Custom S3 endpoint URL. Used as fallback when `endpoint_override` is not specified in backend parameters. Set this for S3-compatible storage services (e.g., MinIO, Ceph). |

The OBJ backend also recognizes standard AWS SDK environment variables for authentication:

| Variable | Type | Description |
|----------|------|-------------|
| `AWS_ACCESS_KEY_ID` | String | AWS access key for authentication. |
| `AWS_SECRET_ACCESS_KEY` | String | AWS secret key for authentication. |
| `AWS_SESSION_TOKEN` | String | AWS session token for temporary credentials. |
| `AWS_REGION` | String | AWS region for the S3 endpoint. |


### Azure Blob Storage

<Note>
These variables apply when using the Azure Blob Storage backend.
</Note>


| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `AZURE_STORAGE_ACCOUNT_URL` | String (URL) | None | Azure Storage account URL (e.g., `https://<account>.blob.core.windows.net`). |
| `AZURE_STORAGE_CONTAINER_NAME` | String | None (required) | Azure Storage container name for blob operations. |
| `AZURE_STORAGE_CONNECTION_STRING` | String | None | Azure Storage connection string. Used for local development with Azurite or when connection string auth is preferred. |
| `AZURE_CA_BUNDLE` | String (path) | None | Custom CA certificate bundle path for Azure HTTPS connections. |

Backend parameters passed to `createBackend()` take precedence over these environment variables. Supported override keys are `account_url`, `container_name`, `connection_string`, and `ca_bundle`.


### GDS (GPUDirect Storage)

<Note>
These variables apply when using the GDS backend.
</Note>


| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `CUFILE_ENV_PATH_JSON` | String (path) | Default cuFile config | Path to the cuFile configuration JSON file. This is a cuFile SDK variable, not NIXL-specific. Override to customize GPUDirect Storage behavior. |


## Quick Reference

Set environment variables before launching your NIXL application:

```bash
# Enable debug logging and telemetry with Prometheus export
export NIXL_LOG_LEVEL=DEBUG
export NIXL_TELEMETRY_ENABLE=true
export NIXL_TELEMETRY_EXPORTER=prometheus
export NIXL_TELEMETRY_PROMETHEUS_PORT=9090

# Configure etcd for distributed metadata exchange
export NIXL_ETCD_ENDPOINTS=http://localhost:2379

# Run your NIXL application
./my_nixl_app
```