19.1. Introduction to PyROOT

Table of Contents

Using ROOT from Python

PyROOT is the Python interface to ROOT. It lets you use almost all ROOT features directly from Python code, so you can combine ROOT’s data analysis, histograms, and TTrees with the flexibility of the Python ecosystem.

At a conceptual level, PyROOT is not a separate program. It is a set of Python bindings that expose ROOT’s C++ classes as Python objects. A TH1F histogram in PyROOT is the same C++ class that you use in C++, only controlled from Python. You can create ROOT objects, call their methods, and pass them around in Python just like any other Python object.

PyROOT is especially useful when you want to:

Work interactively in a Jupyter notebook while still using ROOT’s powerful I/O and plotting.
Glue ROOT analysis with Python libraries such as NumPy, SciPy, or pandas.
Prototype analysis quickly in Python, then later move performance-critical parts to compiled C++ if needed.

You will use the same ROOT class names and methods that appear elsewhere in this course. The main difference is the syntax: you write Python instead of C++. For example, in Python you write

python

import ROOT
h = ROOT.TH1F("h", "Example", 100, 0.0, 10.0)
h.Fill(3.14)
h.Draw()

which corresponds very closely to the equivalent C++ code, but uses Python indentation, no semicolons, and Python’s import system.

The PyROOT module is usually imported under the name ROOT. Once imported, every ROOT class is accessed as an attribute of that module. The table below shows basic correspondences between concepts in C++ ROOT and PyROOT.

Concept	C++ ROOT example	PyROOT example
Include ROOT headers	`#include "TH1F.h"`	`import ROOT`
Create a histogram	`TH1F *h = new TH1F("h","t",100,0,1);`	`h = ROOT.TH1F("h", "t", 100, 0, 1)`
Call a method	`h->Fill(0.5);`	`h.Fill(0.5)`
Draw on canvas	`h->Draw();`	`h.Draw()`
Access ROOT constants	`kRed`	`ROOT.kRed`

In PyROOT you still use C++ class names and method names. Only the language syntax around them is Pythonic. There is no separate "Python version" of ROOT classes.

Another important aspect is that PyROOT talks directly to the C++ libraries that are installed with ROOT. This means that if a C++ class exists in your ROOT installation, you can generally access it immediately from Python without extra wrappers.

Because PyROOT is just another way to drive ROOT, you should think of it as an alternative frontend parallel to the C++ macro and compiled approaches that you learned earlier. The analysis concepts, the ROOT object model, and the file format all stay the same. Only the environment and language you use to control ROOT change.

Starting PyROOT

To start using ROOT from Python, your system must have both Python and ROOT installed, with PyROOT enabled. Many binary ROOT distributions already include PyROOT. If you installed ROOT using a package manager or Conda, PyROOT is usually available automatically once you activate the appropriate environment and set up ROOT.

The most common way to start PyROOT is to use the standard Python interpreter and import the ROOT module. After your shell environment is configured for ROOT, you can run in a terminal:

bash

python

bash

python3

Then inside the Python prompt, import ROOT:

python

import ROOT

If this import runs without errors, PyROOT is available. You can make a quick functional check by creating and drawing a simple histogram:

python

import ROOT
h = ROOT.TH1F("h", "Test histogram", 50, 0.0, 5.0)
for i in range(1000):
    h.Fill(ROOT.gRandom.Gaus(2.5, 0.5))
c = ROOT.TCanvas("c", "Canvas", 800, 600)
h.Draw()
c.Update()

This code should open a ROOT graphics window with a histogram. When running from a terminal, the script might return control to the shell immediately and close the window. To keep the window open, you can add:

python

input("Press Enter to exit")

or, when running from IPython or a Jupyter notebook, ROOT will normally integrate with the event loop and keep the canvas visible while the kernel is running.

You can also start PyROOT from the command line by running a Python script that uses ROOT. Save a file, for example example.py, with:

python

import ROOT
print("ROOT version:", ROOT.gROOT.GetVersion())

Then run:

bash

python example.py

This prints the ROOT version and confirms that Python can load the ROOT libraries.

If the command python refers to a different Python installation than the one where PyROOT is visible, importing ROOT may fail. In that situation, ensure that you are using the Python binary that belongs to your ROOT or Conda environment. For Conda installations, for example, you would typically do:

bash

conda activate myrootenv
python

and then import ROOT inside that environment.

Another popular way to start PyROOT is inside a Jupyter notebook. After configuring your environment, you can launch

bash

jupyter notebook

create a new Python notebook, and in the first cell write:

python

import ROOT
ROOT.gROOT.SetBatch(False)  # allow interactive graphics if needed

From there you can work interactively with ROOT objects, inspect them inline, and combine plots and analysis steps with narrative text and equations.

To use PyROOT successfully, you must start Python from an environment where ROOT is set up. This typically means sourcing ROOT’s thisroot.sh script or activating the Conda environment that provided ROOT, before launching Python or Jupyter.

Once PyROOT is imported, the rest of this ROOT and Python section will show how to create and manipulate histograms, graphs, and TTrees from Python, and how to connect them to common Python tools.

19.1. Introduction to PyROOT

Using ROOT from Python

Starting PyROOT

Comments

Where to Move