Uproot


PyPI version Conda-Forge Python 3.7‒3.11 BSD-3 Clause License Continuous integration tests

Scikit-HEP NSF-1836650 DOI 10.5281/zenodo.4340632 Documentation Gitter


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.

How to install

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

Documentation

ROOT is a C++ toolkit for data analysis, part of which is the ROOT file format. Over an exabyte of particle physics data are stored in ROOT files around the world.

Uproot is a Python implementation of ROOT I/O, independent of the ROOT toolkit itself (including ROOT’s Python interface, PyROOT).

  • If you need help understanding ROOT and its ecosystem, see the ROOT project documentation.

  • If you know what a ROOT file is but are unfamiliar with Uproot, see the Getting started guide.

  • If you are migrating from an older version to Uproot 4 or 5, see the Uproot 3 → 4+ cheat-sheet.

  • If you need detailed descriptions of a class’s properties or a function’s parameters, see the left-bar on this site (≡ button on mobile) or use help in Python, ? or shift-tab in iPython/Jupyter.

Getting help

  • 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.