Uproot 3

3.14.4 · maintenance · verified Thu Apr 16

Uproot 3 is a Python library designed for reading and writing ROOT files, a data format prevalent in high-energy physics, using pure Python and NumPy. It facilitates the conversion of ROOT data into familiar Python data structures like NumPy arrays. This version (3.x) is currently in maintenance mode, superseded by `uproot4`, and receives only critical bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'uproot'
```
cause This typically occurs if you have `uproot3` installed but are trying to import it using the `uproot` name, or if you expected `uproot4` but only `uproot3` is present.

fix If `uproot3` is installed, use `import uproot3`. If you intended to use the latest version (`uproot4`), install it with `pip install uproot4` and then use `import uproot`.
```
ModuleNotFoundError: No module named 'uproot_methods'
```
cause The companion package providing mix-in methods was renamed from `uproot-methods` to `uproot3-methods` in Uproot 3.14.1.

fix Install the correct package (`pip install uproot3-methods`) and update your import statements from `import uproot_methods` to `import uproot3_methods`.
```
TypeError: 'ReadOnlyFile' object is not subscriptable
```
cause This error means you're attempting to use dictionary-like indexing (e.g., `file['tree/branch']`) on an object that isn't compatible with it, or you might be trying to subscript a file that was closed or failed to open.

fix Ensure that the `file` object is indeed an open `uproot3` file object (e.g., returned by `uproot3.open()`) and that you are accessing a valid tree or branch path. Double-check that `uproot3` functions like `uproot3.open()` are being used to get the file object, not standard Python `open()`.

Warnings

deprecated Uproot 3.x is deprecated and in maintenance mode. The actively developed and recommended version is `uproot4`. New projects should use `uproot4` for better performance, features, and modern Python compatibility.
Fix: Migrate to `uproot4` by installing `pip install uproot4` and updating your code to use `import uproot` (uproot4 reclaims the 'uproot' import name).
breaking The auxiliary package `uproot-methods` was renamed to `uproot3-methods` in Uproot 3.14.1 to avoid dependency conflicts, particularly with older `uproot` versions. Explicit imports from `uproot_methods` will cause a `ModuleNotFoundError`.
Fix: Ensure `uproot3-methods` is installed (`pip install uproot3-methods`) and update any import statements from `import uproot_methods` to `import uproot3_methods`.
gotcha Uproot 3.x has specific Python version requirements (>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*) and is best supported on Python 3.5-3.8. While it may run on newer Python 3 versions, it is not actively tested or optimized for them, potentially leading to warnings or subtle incompatibilities.
Fix: For Python 3.9 and newer, it is highly recommended to use `uproot4` instead. If `uproot3` is essential, consider using a Python environment between 3.5 and 3.8.
gotcha Versions of Uproot 3 prior to 3.14.4 could produce numerous `FutureWarning` messages when used with NumPy 1.20 and later, due to internal API usage changes within NumPy.
Fix: Upgrade to Uproot 3.14.4 or later to mitigate most NumPy 1.20 related warnings. For full compatibility with the latest NumPy versions, migrating to `uproot4` is recommended.

Install

pip install uproot3 Install Uproot 3

Imports

uproot3
wrong:
```
import uproot
```
correct:
```
import uproot3
```
The original 'uproot' package was renamed to 'uproot3' starting from version 3.14.0. Using 'import uproot' will fail or import an older, incompatible version if 'uproot3' is installed. For the active version, install `uproot4` and use `import uproot`.

Quickstart

This quickstart demonstrates how to create a simple ROOT file, then open it and read data from specified branches using `uproot3`. It shows accessing a single branch directly and multiple branches via a tree object, converting them into NumPy arrays.

import uproot3
import numpy as np
import os

# Create a dummy ROOT file for demonstration purposes
# In a real application, you would open an existing file
filename = "my_dummy_data.root"

with uproot3.recreate(filename) as file:
    file["tree"] = {"branch1": np.array([1, 2, 3, 4, 5]), "branch2": np.array([10.1, 20.2, 30.3, 40.4, 50.5])}

# Open the ROOT file and read data from a specific branch
with uproot3.open(filename) as file:
    branch_data = file["tree/branch1"].array()
    print(f"Data from branch1: {branch_data}")
    
    # Accessing multiple branches
    tree = file["tree"]
    branch2_data = tree.array("branch2")
    print(f"Data from branch2: {branch2_data}")

# Clean up the dummy file
os.remove(filename)

view raw JSON →