---
id: hepconvert
version: "1.4.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# hepconvert — File conversion package.

License: permissive · Maintenance: active · Downloads: 113.6K/mo

## What it is and what it does

hepconvert is a Python library that simplifies conversion between columnar data formats used in high-energy physics. It currently bridges ROOT (the standard HEP data format) and Parquet, with HDF5 support planned. The library wraps the complexity of multi-step format conversions into single-line Python functions or command-line commands, handling both tree-based data (via merge_root) and histogram aggregation (via add_histograms). It includes built-in features for managing large datasets and controlling compression, making it useful for data pipeline automation and batch processing in physics workflows.

The package depends on uproot for ROOT file I/O, click for CLI scaffolding, and click-default-group for command organization. It targets Python 3.9+ and is actively maintained, though still in early planning stages (Development Status 1). With low install friction and no known vulnerabilities, it's straightforward to add to existing analysis environments.

Use it for:

- Merge multiple ROOT files containing TTrees into a single consolidated file for downstream analysis.
- Combine histograms across multiple ROOT files and write the aggregated results to a new ROOT file.
- Convert ROOT data to Parquet format for use in data science workflows outside the HEP ecosystem.
- Automate batch conversion of large physics datasets as part of a data processing pipeline.
- Simplify one-off file format conversions from the command line without writing custom Python scripts.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

hepconvert converts between columnar file formats—currently ROOT and Parquet, with HDF5 planned—replacing multi-step conversion workflows with single-line Python calls or CLI commands, with built-in support for large datasets and compression control.

Yes, if you work with ROOT files and need straightforward conversion or merging. Low install friction, active maintenance, permissive license, and no security issues make it a safe addition. The early development status (Planning) means the API or feature set may change, so pin the version if you rely on it in production. Best suited for exploratory analysis or pipeline automation rather than mission-critical workflows until it reaches a stable release milestone.

## Install

pip install hepconvert
uv add hepconvert
poetry add hepconvert

## Installing hepconvert

Before you install: Low friction: pure Python wheel with three lightweight runtime dependencies (click, click-default-group, uproot). Active maintenance with recent releases; last commit 2026-07-20. Early-stage project (Development Status 1 - Planning) but functional and regularly updated.

License in practice: Permissive license (BSD) means you can use, modify, and distribute the package with minimal restrictions, typical for scientific software.

Quickstart:

pip install hepconvert

import hepconvert

# Merge ROOT files with TTrees
hepconvert.merge_root("output.root", ["input1.root", "input2.root"])

# Or from CLI:
# hepconvert merge-root [options] output.root input1.root input2.root

Requires Python 3.9 or later; uproot (a runtime dependency) requires compiled C++ bindings for ROOT file I/O, which may need a working C++ build environment on some systems.

Verify before relying:

- Whether HDF5 support is currently available or still planned—description says 'soon will include' but no timeline or release notes confirm implementation status.
- Performance characteristics and memory efficiency for datasets larger than typical RAM—documentation mentions 'managing large datasets' but specifics are not in the fact sheet.
- Compression algorithm options and their trade-offs beyond 'choosing compression levels'.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 113.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ROOT to Parquet conversion, columnar file format converter, HEP data file conversion, ROOT file merger, histogram aggregation, scientific data format bridge, large dataset conversion, hep-data, file-conversion, data-pipeline

[View on SkillFed](https://skillfed.io/packages/hepconvert) · [View on PyPI](https://pypi.org/project/hepconvert/)