Install & Compatibility
Where this runs
tested against v2.4.1 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 19.7s · import 1.507s · 579MB
595MB installed
● package 595MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
extract_u_nk
✓ from alchemlyb.parsing.gmx import extract_u_nk
extract_dHdl
✓ from alchemlyb.parsing.gmx import extract_dHdl
decorrelate_u_nk
✓ from alchemlyb.preprocessing.subsampling import decorrelate_u_nk
MBAR
✓ from alchemlyb.estimators import MBAR
ABFE
✓ from alchemlyb.workflows import ABFE
concat
✓ from alchemlyb import concat
✗ import pandas; pandas.concat()
Use alchemlyb.concat() to ensure metadata propagation for alchemlyb DataFrames.
This quickstart demonstrates how to use the high-level `ABFE` workflow to automatically analyze absolute binding free energy calculations, requiring only a few lines of code. It uses example GROMACS data provided by the `alchemtest` library to parse files, perform data preprocessing, estimate free energies using MBAR, BAR, and TI estimators, and generate diagnostic plots.
import os
from alchemtest.gmx import load_ABFE
from alchemlyb.workflows import ABFE
# This example uses test data from the alchemtest library.
# Ensure alchemtest is installed: `pip install alchemtest`
# Obtain the path of the data
dir_path = os.path.dirname(load_ABFE()['data']['complex'][0])
# Initialize and run the Absolute Binding Free Energy (ABFE) workflow
workflow = ABFE(
units='kcal/mol',
software='GROMACS',
dir=dir_path,
prefix='dhdl',
suffix='xvg',
T=298,
outdirectory='./alchemlyb_output'
)
# Execute the complete workflow with specified parameters
result = workflow.run(
skiptime=10,
uncorr='dhdl',
threshold=50,
estimators=('MBAR', 'BAR', 'TI'),
overlap='O_MBAR.pdf',
breakdown=True,
forwrev=10
)
print("Free energy estimates:")
print(result)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'alchemlyb'
The 'alchemlyb' library is not installed in the Python environment.
fixInstall the library using pip: 'pip install alchemlyb'.
ImportError: cannot import name 'extract_dHdl' from 'alchemlyb.parsing.gmx'
The function 'extract_dHdl' is not available in the 'alchemlyb.parsing.gmx' module.
fixEnsure you are using the correct function name and that your 'alchemlyb' version supports it.
ValueError: The input should be u_nk
The function expects input data in the 'u_nk' format, but received a different format.
fixConvert your input data to the 'u_nk' format before passing it to the function.
DeprecationWarning: Method 'dhdl' has been deprecated, using 'dE' instead. 'dhdl' will be removed in alchemlyb 3.0.0.
The 'dhdl' method is deprecated and will be removed in future versions.
fixUpdate your code to use the 'dE' method instead of 'dhdl'.
DeprecationWarning: Method 'dhdl_all' has been deprecated, using 'all' instead. 'dhdl_all' will be removed in alchemlyb 3.0.0.
The 'dhdl_all' method is deprecated and will be removed in future versions.
fixUpdate your code to use the 'all' method instead of 'dhdl_all'.
Upgrade
Version history
2.5.0latest on PyPI · released Oct 22, 2025
Audit
Dependencies
pandasrequiredCore data structure (DataFrame) and data manipulation; requires >= 2.1 for alchemlyb >= 2.2.0.
pymbarrequiredBackend for MBAR and BAR estimators; alchemlyb 2.x requires >= 4.0.
numpyrequiredFundamental numerical computing library, part of the PyData stack.
logururequiredUsed for logging since alchemlyb 2.1.0.
alchemtestoptionalProvides test data used in tutorials and examples.