Install & Compatibility
Where this runs
tested against v2.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.254s · 118.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.6s · import 0.256s · 110MB
117MB installed
● package 117MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CorrectionSet
✓ from correctionlib import CorrectionSet
schemav2
✓ from correctionlib import schemav2
This quickstart demonstrates how to define a simple 2D binned correction using CorrectionLib's JSON schema, save it to a file, and then load and evaluate it in Python. It shows how to retrieve a specific correction from a `CorrectionSet` and calculate the corrected value for given inputs.
import correctionlib
import os
import json
# Create a dummy JSON correction file content
correction_json_content = '''
{
"schema_version": 2,
"description": "Simple example corrections",
"corrections": [
{
"version": 1,
"name": "my_sf",
"inputs": [
{"name": "x", "type": "real"},
{"name": "y", "type": "real"}
],
"output": {"name": "scale_factor", "type": "real"},
"data": {
"nodetype": "binning",
"input": "x",
"edges": [0.0, 5.0, 10.0],
"content": [
{
"nodetype": "binning",
"input": "y",
"edges": [0.0, 5.0, 10.0],
"content": [
0.9,
1.0
]
},
{
"nodetype": "binning",
"input": "y",
"edges": [0.0, 5.0, 10.0],
"content": [
1.1,
1.2
]
}
],
"flow": "clamp"
}
}
]
}
'''
# Save the content to a temporary file
file_path = "example_correction.json"
with open(file_path, "w") as f:
f.write(correction_json_content)
# Load the corrections from the file
corrections = correctionlib.CorrectionSet.from_file(file_path)
# Access a specific correction
my_correction = corrections["my_sf"]
# Evaluate the correction
# Example 1: x=3.0, y=2.0 (falls in first x-bin, first y-bin)
result1 = my_correction.evaluate(3.0, 2.0)
print(f"Correction for x=3.0, y=2.0: {result1}")
# Example 2: x=7.0, y=6.0 (falls in second x-bin, second y-bin)
result2 = my_correction.evaluate(7.0, 6.0)
print(f"Correction for x=7.0, y=6.0: {result2}")
# Clean up the temporary file
os.remove(file_path)
correction --version
Debug
Known issues
breakingStarting with v2.8.0, the `evaluate()` method will return flat `awkward` arrays when flat `awkward` arrays are passed as input. Previously, it would return `numpy` arrays in this scenario.fixIf `numpy` array output is required, explicitly call `.to_numpy()` on the result, e.g., `my_correction.evaluate(...).to_numpy()`.
affects: >=2.8.0
breakingVersions of CorrectionLib prior to v2.6.0 exhibit silent wrong results for vectorized evaluation when used with `numpy` 2.0. This is a critical compatibility issue.fixUpgrade CorrectionLib to version 2.6.0 or higher to ensure correct vectorized evaluation with `numpy` 2.0+.
affects: <2.6.0 with numpy >=2.0
breakingSince v2.6.0, the representation of infinities in bin edges for correction definitions has changed from floating-point values to string literals (`"inf"` or `"-inf"`). Older JSON files might not be forward-compatible without conversion.fixUpdate your correction JSON files to use `"inf"` or `"-inf"` strings for infinite bin edges as per the updated schema. Version 2.6.1 allows reading older JSONs for backwards compatibility, but authoring new ones should use strings.
affects: >=2.6.0 (for JSON definitions)
breakingPython 3.6 support has been officially dropped starting from v2.5.0. The library now requires Python 3.9 or newer.fixEnsure your environment is running Python 3.9 or a more recent compatible version.
affects: >=2.5.0
gotchaCorrectionLib migrated to `pydantic` v2 in v2.5.0. Users interacting directly with CorrectionLib's schema models (e.g., `correctionlib.schemav2.CorrectionSet`) should be aware of `pydantic` v1 vs v2 breaking changes, particularly method renames (e.g., `dict()` to `model_dump()`) and configuration changes.fixConsult the official `pydantic` v1 to v2 migration guide. `bump-pydantic` is a tool available to assist with automated code migration.
affects: >=2.5.0
gotchaWhen installing `correctionlib` and planning to use its C++ evaluator (e.g., from ROOT or a standalone executable), C++ ABI compatibility between the installed library and your environment is crucial. Mismatches can lead to linker errors.fixTo avoid ABI issues, install `correctionlib` by forcing a source build within your environment: `pip install --no-binary=correctionlib correctionlib`. This ensures C++ components are compiled with compatible settings.
affects: All versions (when compiling from source/using C++ bindings)
Errors
Common errors & fixes
undefined symbol: _ZN10correction13CorrectionSet9from_file
This linker error typically occurs in C++ environments (like ROOT or CMSSW) when the C++ components of `correctionlib` (e.g., installed via Python wheels) have an ABI incompatibility with the C++ compiler/environment being used.
fixInstall `correctionlib` from source to ensure its C++ components are built with the compatible ABI of your environment. Use `pip install --no-binary=correctionlib correctionlib`. For CMSSW, specific installation recipes might be required.
error: cannot cast private base class 'std::__detail::__variant::_Variant_storage<false, int, double, std::__cxx11::basic_string<char> >' to 'std::variant<int, double, std::__cxx11::basic_string<char> >'
This C++ compilation error, often seen when calling `Correction::evaluate` within ROOT or similar environments, arises from type mismatches or ABI incompatibilities when converting arguments to `std::vector<std::variant<int, double, std::string>>`. String literals might not be correctly implicitly converted to `std::string` for the `std::variant` type.
fixExplicitly construct `std::string` objects for string literals when passing them to `evaluate`, for example, `corr->evaluate({std::string("central"), std::string("M"), 5, 1.2, 240.})`. Ensure the `correctionlib` C++ library is built with a compiler and C++ standard compatible with the calling environment. pydantic.ValidationError
The input JSON file provided to `correctionlib` does not conform to its defined schema (Schema v1 or v2). This can be due to incorrect field names, missing required fields, invalid types for values, or structural inconsistencies in the correction definitions.
fixReview your JSON file against the `correctionlib` schema documentation (e.g., `schemav2.html`) and ensure all corrections, binnings, categories, and other elements are correctly structured and typed. Tools or IDEs might offer validation against the published JSON schema URL.
ModuleNotFoundError: No module named 'correctionlib'
The `correctionlib` Python package is not installed in your current Python environment, or the Python interpreter you are using does not have access to the installed package.
fixInstall the package using `pip install correctionlib`. If you are working within a virtual environment, ensure it is activated. For specific environments like CMSSW, follow the recommended installation procedures.
Upgrade
Version history
2.9.0latest on PyPI · released Jun 16, 2026
Audit
Dependencies
numpyrequiredUsed for vectorized evaluation and array manipulation.
awkwardrequiredUsed for vectorized evaluation, especially with jagged array inputs/outputs.
pydanticrequiredUsed for schema validation and parsing of correction definitions.
pybind11requiredCore component for Python bindings to the C++ evaluator.