Install & Compatibility
Where this runs
tested against v0.11.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.930 runs
build_error
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 14.0s · import 0.000s · 358MB
369MB installed
● package 369MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HDF5Database
✓ from ase_db_backends import HDF5Database
✗ from ase_db_backends import HDF5Database
This quickstart demonstrates how to initialize an HDF5 database backend, store an `ase.Atoms` object with key-value pairs and additional data, and then retrieve it. This pattern is similar for other backends like MongoDB or JSON/ZODB.
import os
from ase.atoms import Atoms
from ase.build import molecule
from ase_db_backends.hdf5 import HDF5Database
# Clean up previous run for repeatability
if os.path.exists('test_ase_backend.hdf5'):
os.remove('test_ase_backend.hdf5')
# 1. Create an Atoms object
h2o = molecule('H2O')
h2o.info['user_note'] = 'A test molecule'
# 2. Instantiate the HDF5 backend
# Replace 'test_ase_backend.hdf5' with your desired filename
db = HDF5Database('test_ase_backend.hdf5')
# 3. Write the Atoms object to the database
# You can also add key-value pairs for searching
row_id = db.write(h2o,
key_value_pairs={'formula': 'H2O', 'source': 'ase_example'},
data={'energy_dft': -10.0}) # Arbitrary data can be stored
print(f"Stored H2O molecule with row_id: {row_id}")
# 4. Read back from the database (example for iterating)
# Note: Iterating returns (id, atoms, kvp, data)
print("\nRetrieving stored data:")
for r_id, atoms_read, kvp_read, data_read in db.select():
print(f" Read row_id: {r_id}")
print(f" Formula: {atoms_read.get_chemical_formula()}")
print(f" Label from KVP: {kvp_read.get('formula')}")
print(f" Energy from data: {data_read.get('energy_dft')}")
# Clean up
if os.path.exists('test_ase_backend.hdf5'):
os.remove('test_ase_backend.hdf5')
Debug
Known issues
breakingThe `ase-db-backends` library requires `ase` version 3.23 or newer. Using older `ase` versions can lead to `AttributeError` or `TypeError` due to API incompatibilities.fixEnsure your ASE installation is `ase>=3.23` by running `pip install --upgrade ase`.
affects: <0.11.0 (implicitly, by `ase` dependency)
gotchaUnlike `ase.db.connect`, you must explicitly instantiate the backend class (e.g., `HDF5Database`) and use its methods. The `ase.db.connect` function does not directly support backend-specific configuration arguments like `filename` or `mongo_url` from this library.fixDo not use `ase.db.connect(filename='my_db.hdf5')`. Instead, use `from ase_db_backends.hdf5 import HDF5Database; db = HDF5Database('my_db.hdf5')`. affects: All
gotchaEach backend (HDF5, MongoDB, JSON) requires specific extra dependencies. If you install `ase-db-backends` without extras, you might encounter `ModuleNotFoundError` when trying to use a backend.fixInstall the library with the necessary extras, e.g., `pip install ase-db-backends[hdf5]` for HDF5 support, or `pip install ase-db-backends[all]` for all backends.
affects: All
Upgrade
Version history
0.11.0latest on PyPI · released Nov 12, 2025
Audit
Dependencies
aserequiredCore functionality relies on ASE Atoms objects and utilities.
h5pyoptionalRequired for the HDF5 backend.
pymongooptionalRequired for the MongoDB backend.
ZODBoptionalRequired for the ZODB/JSON backend.