Skip to content

Installation

Requirements

  • Python 3.11+
  • ASE (Atomic Simulation Environment)

aseview 0.0.14 and newer require Python 3.11 or newer. If you need Python 3.10 support, install the last compatible release, 0.0.13:

pip install "aseview<0.0.14"

Install from PyPI

pip install aseview

Install from Source

git clone https://github.com/kangmg/aseview.git
cd aseview
python3 scripts/run_locked_verification.py python -m pytest tests/test_imports.py -q

For contributor QA, use the committed hash-locked verification runner rather than validating docs or release behavior through an editable checkout install.

Optional: PNG/GIF Export

pip install "aseview[export]"
python -m playwright install chromium

The export extra pins a legacy Playwright browser range for CentOS 7/glibc 2.17 compatibility. Newer Playwright browser builds may require newer glibc even if the Python package installs successfully.

Optional: Cube Surfaces

Install the surface extra to use SurfaceViewer with Gaussian CUBE orbital, density, and delta-density data:

pip install "aseview[surface]"

This extra installs cvve, which provides the cube import surface used by aseview, plus the marching-cubes extraction dependency. It is not needed for standard MolecularViewer, OverlayViewer, NormalViewer, FragSelector, or view() usage.

Dependencies

aseview will automatically install the following dependencies:

Package Purpose
ase Atomic structure handling
numpy Numerical operations
typer CLI framework
rich Terminal formatting

Optional extras:

Extra Purpose
[export] Python PNG/GIF export through Playwright
[surface] Cube-backed SurfaceViewer isosurfaces

Standard notebook display for MolecularViewer, OverlayViewer, NormalViewer, FragSelector, SurfaceViewer, LiteViewer, and view() is available with the base install. The [export] extra is only required for the Python save_png() / save_gif() helpers, and [surface] is only required for cube-backed volumetric inputs.

Verify Installation

# Check CLI
aseview --help

# Check Python import
python -c "from aseview import MolecularViewer; print('OK')"

Contributor docs verification

When changing documentation, validate through the committed hash-locked runner:

python3 scripts/run_locked_verification.py python scripts/verify_docs.py --strict

This command uses the committed verification locks and regenerates the docs viewer artifacts before the strict MkDocs build.

Note on aseview2

aseview2 is kept as a backward-compatible alias for aseview. Both commands are identical:

aseview molecule.xyz   # recommended
aseview2 molecule.xyz  # alias (backward compatibility)