uproot 5.0.0rc4

ROOT I/O in pure Python and NumPy.

Uproot is a library for reading and writing ROOT files in pure Python and NumPy.

Unlike the standard C++ ROOT implementation, Uproot is only an I/O library, primarily intended to stream data into machine learning libraries in Python. Unlike PyROOT and root_numpy, Uproot does not depend on C++ ROOT. Instead, it uses Numpy to cast blocks of data from the ROOT file as Numpy arrays.

Installation

Uproot can be installed from PyPI using pip. Awkward Array is optional but highly recommended:

pip install uproot awkward

Uproot is also available using conda (in this case, Awkward Array is automatically installed):

conda install -c conda-forge uproot

If you have already added conda-forge as a channel, the -c conda-forge is unnecessary. Adding the channel is recommended because it ensures that all of your packages use compatible versions (see conda-forge docs):

conda config --add channels conda-forge
conda update --all

Getting help

Start with the tutorials and reference documentation.

• Report bugs, request features, and ask for additional documentation on GitHub Issues.
• If you have a "How do I...?" question, start a GitHub Discussion with category "Q&A".
• Alternatively, ask about it on StackOverflow with the [uproot] tag. Be sure to include tags for any other libraries that you use, such as Pandas or PyTorch.
• To ask questions in real time, try the Gitter Scikit-HEP/uproot chat room.

Installation for developers

Uproot is an ordinary Python library; you can get a copy of the code with

git clone https://github.com/scikit-hep/uproot4.git

and install it locally by calling pip install . in the repository directory.

If you need to develop Awkward Array as well, see its installation for developers.

Dependencies

Uproot's only strict dependencies are NumPy and packaging. You'll also need importlib_metadata if you are on Python 3.7. These will be automatically installed when you install uproot.

Awkward Array is highly recommended. It is not a strict dependency, but is included in the dependencies to help most users; install without dependencies (--no-deps with pip) if you want to avoid awkward. If you're using Uproot without Awkward Array, you'll have to use the library="np" option or globally set uproot.default_library to return arrays as NumPy arrays (see documentation).

• awkward: be sure to use Awkward Array 1.x.

The following libraries are also useful in conjunction with Uproot, but are not necessary. If you call a function that needs one, you'll be prompted to install it. (Conda installs most of these automatically.)

For ROOT files, compressed different ways:

• lz4 and xxhash: only if reading ROOT files that have been LZ4-compressed.
• zstandard: only if reading ROOT files that have been ZSTD-compressed.

For remote data:

• xrootd: only if reading files with root:// URLs.

For exporting data to other libraries:

• pandas: only if library="pd".
• cupy: only if library="cp" (reads arrays onto GPUs).
• boost-histogram: only if converting histograms to boost-histogram with histogram.to_boost().
• hist: only if converting histograms to hist with histogram.to_hist().

Acknowledgements

Support for this work was provided by NSF cooperative agreement OAC-1836650 (IRIS-HEP), grant OAC-1450377 (DIANA/HEP) and PHY-1520942 (US-CMS LHC Ops).

Thanks especially to the gracious help of Uproot contributors (including the original repository).

Jim Pivarski 💻 📖 🚇 🚧	Pratyush Das 💻 🚇	Chris Burr 💻 🚇	Dmitri Smirnov 💻	Matthew Feickert 🚇	Tamas Gal 💻	Luke Kreczko 💻 ⚠️
Nicholas Smith 💻	Noah Biederbeck 💻	Oksana Shadura 💻 🚇	Henry Schreiner 💻 🚇 ⚠️	Mason Proffitt 💻 ⚠️	Jonas Rembser 💻	benkrikler 💻
Hans Dembinski 📖	Marcel R. 💻	Ruggero Turra 💻	Jonas Rübenach 💻	bfis 💻	Raymond Ehlers 💻	Andrzej Novak 💻
Josh Bendavid 💻	Doug Davis 💻	Chao Gu 💻	Lukas Koch 💻	Michele Peresano 💻	Edoardo 💻	JMSchoeffmann 💻
alexander-held 💻	Giordon Stark 💻	Ryunosuke O'Neil 💻	ChristopheRappold 📖	Cosmin Deaconu ⚠️ 💻	Carlos Pegueros 📖 💡 ⚠️ ✅	Benjamin Tovar 💻
Duncan Macleod 🚇	mpad 💻	Peter Fackeldey 💻	Kush Kothari 💻	Aryan Roy 💻	Jerry Ling 💻	kakwok 💻
Dmitry Kalinkin 💻 🚇	Nikolai Hartmann 💻	Kilian Lieret 📖	Daniel Cervenkov 💻	Beojan Stanislaus 💻	Angus Hollands 💻 🚧

💻: code, 📖: documentation, 🚇: infrastructure, 🚧: maintainance, ⚠: tests/feedback, 🤔: foundational ideas.