{"id":4838,"library":"uproot","title":"Uproot","description":"Uproot is a Python library designed for reading and writing files in the ROOT format, commonly used in high-energy physics. It provides ROOT I/O functionality in pure Python and NumPy, without requiring the C++ ROOT installation. As part of the Scikit-HEP project, Uproot efficiently integrates with modern Python data analysis tools like NumPy and Awkward Array. The library is actively maintained, currently at version 5.7.3, with frequent updates and bug fixes.","status":"active","version":"5.7.3","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/uproot5","tags":["ROOT","HEP","physics","data-analysis","numpy","awkward","I/O","scikit-hep"],"install":[{"cmd":"pip install uproot","lang":"bash","label":"Install Uproot"}],"dependencies":[{"reason":"Primary library for handling jagged arrays, highly recommended for most Uproot use cases.","package":"awkward","optional":false},{"reason":"Core dependency for array operations and data representation.","package":"numpy","optional":false},{"reason":"Fast compression library used internally by Uproot.","package":"cramjam","optional":false},{"reason":"Fast hashing algorithm used for caching and data integrity checks.","package":"xxhash","optional":false},{"reason":"Filesystem abstraction layer, enabling Uproot to work with various storage backends (e.g., S3, XRootD).","package":"fsspec","optional":false},{"reason":"Used for version comparisons and managing dependencies.","package":"packaging","optional":false},{"reason":"Recommended for handling physics-specific vector objects (e.g., Lorentz vectors) with Uproot.","package":"vector","optional":true},{"reason":"Enables reading ROOT files from Amazon S3 storage.","package":"s3fs","optional":true},{"reason":"Provides XRootD protocol support for accessing remote ROOT files.","package":"xrootd","optional":true},{"reason":"Optional dependency for handling LZ4-compressed ROOT files.","package":"lz4","optional":true},{"reason":"Optional dependency for handling ZSTD-compressed ROOT files.","package":"zstandard","optional":true}],"imports":[{"symbol":"uproot","correct":"import uproot"},{"note":"Awkward Array is highly recommended for working with jagged data from ROOT files.","symbol":"ak","correct":"import awkward as ak"}],"quickstart":{"code":"import uproot\nimport awkward as ak\n\n# Open a remote ROOT file using XRootD protocol\n# A real-world ROOT file (CMS Open Data example)\nfile_url = 'root://eospublic.cern.ch//eos/opendata/cms/derived-data/AOD2NanoAODOutreachTool/ForHiggsTo4Leptons/SMHiggsToZZTo4L.root'\n\nwith uproot.open(file_url) as file:\n    # List keys (objects) in the ROOT file\n    print(f\"File keys: {file.keys()}\")\n\n    # Access a TTree named 'Events'\n    events = file['Events']\n    print(f\"\\nTree name: {events.name}\")\n    print(f\"Number of entries: {events.num_entries}\")\n\n    # List branches (columns) in the TTree\n    print(f\"\\nBranches in 'Events': {events.keys()}\")\n\n    # Read a single branch (e.g., 'Muon_pt') into an Awkward Array\n    muon_pt = events['Muon_pt'].array()\n    print(f\"\\nFirst 5 Muon_pt values: {muon_pt[:5]}\")\n    print(f\"Type of Muon_pt: {type(muon_pt)}\")\n\n    # Read multiple branches into a dictionary of Awkward Arrays\n    # (or a single record array if 'library=\"ak\"' is explicit or default)\n    muon_data = events.arrays(['Muon_pt', 'Muon_eta', 'Muon_phi'], library='ak')\n    print(f\"\\nFirst entry of Muon_data: {muon_data[0]}\")\n    print(f\"Type of Muon_data: {type(muon_data)}\")\n\n    # Example: filter events (apply a 'cut') and get a branch\n    # (Requires a numerical array for comparison, assume 'Muon_pt' is always present)\n    if 'Muon_pt' in events.keys():\n        high_pt_muons = events.arrays('Muon_pt', cut='nMuon > 0 && Muon_pt[0] > 20', library='ak')\n        print(f\"\\nNumber of events with a leading muon pt > 20: {len(high_pt_muons)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Review 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.","message":"Uproot 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`).","severity":"breaking","affected_versions":"uproot <= 3.x to uproot >= 4.x"},{"fix":"Instead 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.","message":"The `TTree.array()` method for reading a single branch from a TTree has been deprecated and removed in Uproot 4 and 5.","severity":"deprecated","affected_versions":"uproot >= 4.0"},{"fix":"For 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`.","message":"While 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"Calling `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult 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`.","message":"Writing 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).","severity":"gotcha","affected_versions":"uproot >= 4.x"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}