---
name: fsspec-xrootd
description: >-
  Use when accessing ROOT files on EOS, WLCG storage, or another XRootD
  endpoint from Python through fsspec: opening root:// URIs with uproot,
  listing remote directories, handling authentication, or diagnosing XRootD
  path and timeout failures.
---

# fsspec-xrootd

`fsspec-xrootd` exposes XRootD storage through the fsspec interface. Prefer
read-only access unless the user explicitly requests and is authorized for a
write operation.

## Common patterns

Uproot can open an XRootD URI directly when the Python XRootD dependency is
available:

```python
import uproot

uri = "root://storage.example.org//path/to/file.root"
with uproot.open(uri) as root_file:
    events = root_file["Events"].arrays(["mass", "weight"], library="ak")
```

Use fsspec when directory operations or file-like objects are needed:

```python
import fsspec

fs = fsspec.filesystem("root", hostid="storage.example.org")
print(fs.ls("/path/to/data"))

with fs.open("/path/to/data/file.root", "rb") as source:
    payload = source.read(1024)
```

For many ROOT files, pass complete `root://` URIs to `uproot.iterate` or
`uproot.concatenate` and include the tree name explicitly.

## Checks before debugging Python

- Preserve the `root://host//absolute/path` double slash when required by the
  endpoint.
- Test reachability and the exact path with the site's supported XRootD client
  commands.
- Establish the credential required by that endpoint—X.509 proxy, bearer
  token, or anonymous access—before launching the Python client.
- Confirm that the credential is visible in the environment that starts the
  agent or batch job.
- Start with one small file. Tune timeouts, workers, and caching only after the
  basic read succeeds.

Do not embed tokens, proxies, private endpoints, or user paths in committed
configuration. Remote files may be large; iterate in chunks instead of loading
an unbounded dataset eagerly.