Install & Compatibility
Where this runs
tested against v3.29.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.266s · 342.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 12.8s · import 0.268s · 330MB
347MB installed
● package 347MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Atoms
✓ from ase import Atoms
EMT
✓ from ase.calculators.emt import EMT
Example of importing a built-in calculator.
BFGS
✓ from ase.optimize import BFGS
Example of importing an optimizer.
This example demonstrates how to create an `Atoms` object, attach a simple `EMT` calculator, perform a geometry optimization using `BFGS`, and save the final structure and energy. ASE defaults to eV and Å for units.
from ase import Atoms
from ase.calculators.emt import EMT
from ase.optimize import BFGS
from ase.io import write
# Create a molecule (H2)
h2 = Atoms('H2', positions=[[0, 0, 0], [0, 0, 0.7]])
# Attach a calculator (Empirical Potential)
h2.calc = EMT()
# Optimize the geometry
optimizer = BFGS(h2, trajectory='h2.traj')
optimizer.run(fmax=0.02)
# Print final energy and write structure
print(f'Final potential energy: {h2.get_potential_energy():.3f} eV')
write('H2.xyz', h2)
ase --version
Debug
Known issues
breakingASE now requires Python 3.10 or newer, starting with version 3.27.0. Ensure your Python environment meets this requirement.fixUpgrade Python to 3.10+ or use an older ASE version if Python 3.9- is required.
affects: >=3.27.0
breakingThe `ase.ga` (genetic algorithm) module has moved to a standalone project, `ase-ga`, in version 3.27.0. It is no longer part of the main `ase` package.fixInstall `ase-ga` separately via `pip install ase-ga` if you use genetic algorithms.
affects: >=3.27.0
breakingThe Optimizable interface (used by Optimizers) changed in version 3.26.0 to work with arbitrary degrees of freedom instead of Cartesian (Nx3) ones. This can break code that uses internal Optimizer features like `converged()`.fixReview custom optimizer implementations or code interacting with optimizer internals. Adapt to the new arbitrary degrees of freedom interface.
affects: >=3.26.0
breakingThe `ase.io.orca.read_orca_output` function now returns an `Atoms` object with attached properties, instead of just a results dictionary. The previous behavior is available via `ase.io.orca.read_orca_outputs()`.fixAdjust code that reads ORCA output to expect an `Atoms` object, or explicitly call `read_orca_outputs()` for the dictionary-only return.
affects: >=3.25.0
deprecatedThe `master` parameter to Optimizers is now keyword-only. The `force_consistent` option has been removed from `Optimizer`.fixPass `master` as a keyword argument (e.g., `BFGS(atoms, master=...)`) and remove any usage of `force_consistent` from optimizer initialization.
affects: >=3.24.0 (exact version for `force_consistent` removal is not specified, but mentioned around 3.25.0 news)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ase'
ASE is not installed or the Python environment cannot locate it.
fixEnsure ASE is installed using pip: `pip install ase`. If installed, verify that the Python environment's PATH includes the ASE installation directory.
AttributeError: module 'ase' has no attribute 'io'
The 'ase.io' submodule is not automatically imported with 'import ase'.
fixImport the submodule explicitly: `from ase import io` or `from ase.io import read`.
ImportError: No module named 'ase.build'
The 'ase.build' module is not found, possibly due to an incomplete installation or incorrect import.
fixEnsure ASE is correctly installed and import the module with: `from ase.build import fcc111`.
ValueError: builtins.type size changed, may indicate binary incompatibility. Expected 888 from C header, got 880 from PyObject
Binary incompatibility between installed packages, often due to mismatched versions of dependencies like NumPy.
fixUpdate or reinstall NumPy and ASE to compatible versions: `pip install --upgrade numpy ase`.
TclError: no display name and no $DISPLAY environment variable
The ASE GUI requires a display environment, which is unavailable in headless systems or remote sessions.
fixSet the DISPLAY environment variable if a display is available, or use ASE's non-GUI functions in headless environments.
Upgrade
Version history
3.29.0latest on PyPI · released Jun 21, 2026
Audit
Dependencies
numpyrequiredCore dependency for numerical operations, especially array handling.
python3-tkoptionalRequired for the Graphical User Interface (GUI) on some systems (e.g., Debian/Ubuntu).
ase-gaoptionalThe `ase.ga` module moved to a standalone project `ase-ga` in version 3.27.0. Install separately if genetic algorithm functionality is needed.