{"id":7839,"library":"uproot3","title":"Uproot 3","description":"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.","status":"maintenance","version":"3.14.4","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/uproot3","tags":["physics","HEP","ROOT","data-processing","numerical-computing","legacy"],"install":[{"cmd":"pip install uproot3","lang":"bash","label":"Install Uproot 3"}],"dependencies":[{"reason":"Fundamental for array manipulation and data representation as Uproot converts ROOT data into NumPy arrays.","package":"numpy"},{"reason":"Provides mix-in methods for awkward and jagged arrays, essential for handling complex ROOT data structures.","package":"uproot3-methods","optional":false}],"imports":[{"note":"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`.","wrong":"import uproot","symbol":"uproot3","correct":"import uproot3"}],"quickstart":{"code":"import uproot3\nimport numpy as np\nimport os\n\n# Create a dummy ROOT file for demonstration purposes\n# In a real application, you would open an existing file\nfilename = \"my_dummy_data.root\"\n\nwith uproot3.recreate(filename) as file:\n    file[\"tree\"] = {\"branch1\": np.array([1, 2, 3, 4, 5]), \"branch2\": np.array([10.1, 20.2, 30.3, 40.4, 50.5])}\n\n# Open the ROOT file and read data from a specific branch\nwith uproot3.open(filename) as file:\n    branch_data = file[\"tree/branch1\"].array()\n    print(f\"Data from branch1: {branch_data}\")\n    \n    # Accessing multiple branches\n    tree = file[\"tree\"]\n    branch2_data = tree.array(\"branch2\")\n    print(f\"Data from branch2: {branch2_data}\")\n\n# Clean up the dummy file\nos.remove(filename)","lang":"python","description":"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."},"warnings":[{"fix":"Migrate to `uproot4` by installing `pip install uproot4` and updating your code to use `import uproot` (uproot4 reclaims the 'uproot' import name).","message":"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.","severity":"deprecated","affected_versions":"All 3.x versions"},{"fix":"Ensure `uproot3-methods` is installed (`pip install uproot3-methods`) and update any import statements from `import uproot_methods` to `import uproot3_methods`.","message":"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`.","severity":"breaking","affected_versions":">=3.14.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.9"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.14.4"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"ModuleNotFoundError: No module named 'uproot'"},{"fix":"Install the correct package (`pip install uproot3-methods`) and update your import statements from `import uproot_methods` to `import uproot3_methods`.","cause":"The companion package providing mix-in methods was renamed from `uproot-methods` to `uproot3-methods` in Uproot 3.14.1.","error":"ModuleNotFoundError: No module named 'uproot_methods'"},{"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()`.","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.","error":"TypeError: 'ReadOnlyFile' object is not subscriptable"}]}