Install & Compatibility
Where this runs
tested against v5.7.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.292s · 117.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.0s · import 1.242s · 109MB
116MB installed
● package 116MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ak
✓ import awkward as ak
Awkward Array is highly recommended for working with jagged data from ROOT files.
This quickstart demonstrates how to open a remote ROOT file, inspect its contents, and read data from a TTree into Awkward Arrays. It includes examples for reading single or multiple branches and applying simple cuts.
import uproot
import awkward as ak
# Open a remote ROOT file using XRootD protocol
# A real-world ROOT file (CMS Open Data example)
file_url = 'root://eospublic.cern.ch//eos/opendata/cms/derived-data/AOD2NanoAODOutreachTool/ForHiggsTo4Leptons/SMHiggsToZZTo4L.root'
with uproot.open(file_url) as file:
# List keys (objects) in the ROOT file
print(f"File keys: {file.keys()}")
# Access a TTree named 'Events'
events = file['Events']
print(f"\nTree name: {events.name}")
print(f"Number of entries: {events.num_entries}")
# List branches (columns) in the TTree
print(f"\nBranches in 'Events': {events.keys()}")
# Read a single branch (e.g., 'Muon_pt') into an Awkward Array
muon_pt = events['Muon_pt'].array()
print(f"\nFirst 5 Muon_pt values: {muon_pt[:5]}")
print(f"Type of Muon_pt: {type(muon_pt)}")
# Read multiple branches into a dictionary of Awkward Arrays
# (or a single record array if 'library="ak"' is explicit or default)
muon_data = events.arrays(['Muon_pt', 'Muon_eta', 'Muon_phi'], library='ak')
print(f"\nFirst entry of Muon_data: {muon_data[0]}")
print(f"Type of Muon_data: {type(muon_data)}")
# Example: filter events (apply a 'cut') and get a branch
# (Requires a numerical array for comparison, assume 'Muon_pt' is always present)
if 'Muon_pt' in events.keys():
high_pt_muons = events.arrays('Muon_pt', cut='nMuon > 0 && Muon_pt[0] > 20', library='ak')
print(f"\nNumber of events with a leading muon pt > 20: {len(high_pt_muons)}")
Debug
Known issues
breakingUproot 4 and 5 introduced significant API changes compared to Uproot 3, particularly concerning how TTree methods return arrays and the underlying Awkward Array version. Uproot 3 used Awkward 0.x, while Uproot 4/5 uses Awkward 1.x (now just `awkward`).fixReview the Uproot 3 → 4+ cheat-sheet in the official documentation. The `TTree.array()` method for reading a single branch was removed; use `TTree[branch_name].array()` or `TTree.arrays([branch_name])`. For multiple branches, `TTree.arrays()` is the primary method.
affects: uproot <= 3.x to uproot >= 4.x
deprecatedThe `TTree.array()` method for reading a single branch from a TTree has been deprecated and removed in Uproot 4 and 5.fixInstead of `tree.array('branch_name')`, use `tree['branch_name'].array()` or `tree.arrays(['branch_name'], library='ak')[0]` for a single branch. For multiple branches, `tree.arrays(['b1', 'b2'], library='ak')` is the idiomatic way. affects: uproot >= 4.0
gotchaWhile Uproot can return NumPy arrays (`library='np'`), using NumPy for jagged data (e.g., variable-length arrays per event) can lead to performance degradation. NumPy arrays of Python objects negate vectorized performance benefits.fixFor optimal performance and convenient manipulation of jagged arrays, always use `awkward` (the default `library='ak'`) when dealing with such data structures in ROOT files. Explicitly `import awkward as ak`.
affects: All versions
gotchaCalling `TTree.arrays()` to read a large number of branches or a very large dataset into memory at once can lead to out-of-memory errors or significant performance issues.fixFor very large files or many branches, consider using `uproot.iterate` to process data in chunks (batches) or selectively load only the necessary branches. This allows for memory-efficient processing.
affects: All versions
gotchaWriting ROOT files with Uproot 4/5 has certain limitations compared to the full C++ ROOT implementation. Features like updating existing files (uproot.update) or writing complex nested C++ objects directly might not be fully supported or have specific constraints (e.g., basket sizes).fixConsult the latest Uproot documentation on writing ROOT files for current capabilities and limitations. For advanced writing needs, a C++ ROOT installation or other specialized tools might be required. Simple writing of histograms and TTrees with flat or basic jagged data is supported via `uproot.recreate`.
affects: uproot >= 4.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'uproot'
This error occurs when the 'uproot' library is not installed in the Python environment.
fixInstall uproot using pip: 'pip install uproot'.
AttributeError: 'ROOTDirectory' object has no attribute 'classnames'
This error occurs when attempting to call a non-existent method 'classnames' on a 'ROOTDirectory' object in uproot.
fixUse the correct method to inspect the contents of the ROOT file, such as 'file.keys()' to list the keys or 'file.classnames()' to get a dictionary of keys and their corresponding classes.
ImportError: install the 'hist' package with:
pip install hist
This error occurs when attempting to use the 'to_hist()' method in uproot without having the 'hist' package installed.
fixInstall the 'hist' package using pip: 'pip install hist'.
KeyError: 'no such branch'
This error, or a more specific `uproot.KeyInFileError`, occurs when attempting to access a non-existent branch, tree, or object within an opened ROOT file using dictionary-like syntax (e.g., `file['non_existent_branch']`).
fixVerify the exact name of the branch or object you intend to access. Use `file.keys()` or `file.classnames()` to list available top-level objects, and for trees, use `tree.keys()` or `tree.show()` to inspect available branches. Ensure case sensitivity and correct spelling.
FileNotFoundError: [Errno 2] No such file or directory: 'your_file.root'
The specified ROOT file path for `uproot.open()` is incorrect, the file does not exist at that location, or the program does not have permission to access it.
fixDouble-check the file path for typos, ensure the file exists at the given location, and verify that the program has read permissions for the file and its directory. Use an absolute path or ensure the file is in the current working directory.
Upgrade
Version history
5.7.6latest on PyPI · released Aug 20, 2026
Audit
Dependencies
awkwardrequiredPrimary library for handling jagged arrays, highly recommended for most Uproot use cases.
numpyrequiredCore dependency for array operations and data representation.
cramjamrequiredFast compression library used internally by Uproot.
xxhashrequiredFast hashing algorithm used for caching and data integrity checks.
fsspecrequiredFilesystem abstraction layer, enabling Uproot to work with various storage backends (e.g., S3, XRootD).
packagingrequiredUsed for version comparisons and managing dependencies.
vectoroptionalRecommended for handling physics-specific vector objects (e.g., Lorentz vectors) with Uproot.
s3fsoptionalEnables reading ROOT files from Amazon S3 storage.
xrootdoptionalProvides XRootD protocol support for accessing remote ROOT files.
lz4optionalOptional dependency for handling LZ4-compressed ROOT files.
zstandardoptionalOptional dependency for handling ZSTD-compressed ROOT files.