xyzrender: Publication-quality molecular graphics.

Render molecular structures as publication-quality SVG, PNG, PDF, and animated GIF from XYZ, mol/SDF, MOL2, PDB, SMILES, CIF, cube files, or quantum chemistry output — from the command line or from Python/Jupyter.

xyzrender turns XYZ files and quantum chemistry input/output (MOl, MOL2, SDF, PDB, ORCA, Gaussian, Q-Chem, etc.) into clean SVG, PNG, PDF, and animated GIF graphics — ready for papers, presentations, and supporting information. The SVG rendering approach is built on and inspired by xyz2svg by Ksenia Briling @briling.

Most molecular visualisation tools require manual setup: loading files into a GUI, tweaking camera angles, exporting at the right resolution and adding specific TS or NCI bonds. xyzrender skips this. One command gives you a (mostly) oriented, depth-cued structure with correct bond orders, aromatic ring rendering, automatic bond connectivity, with TS bonds and NCI bonds. Orientation control is available through an interface to v by Ksenia Briling @briling.

TS bimp full nci

What it handles out of the box:

Bond orders and aromaticity — double bonds, triple bonds, and aromatic ring notation detected automatically from geometry via xyzgraph
Transition state bonds — forming/breaking bonds rendered as dashed lines, detected automatically from imaginary frequency vibrations via graphRC
Non-covalent interactions — hydrogen bonds and other weak interactions shown as dotted lines, detected automatically via xyzgraph
GIF animations — rotation, TS vibration, and trajectory animations for presentations
Molecular orbitals — render MO lobes from cube files with front/back depth cueing
Electron density surfaces — depth-graded translucent isosurfaces from density cube files
Electrostatic potential (ESP) — ESP colormapped onto the density surface from paired cube files
vdW surface overlays — van der Waals spheres on all or selected atoms
Structural overlay — RMSD-align two conformers and render in contrasting colours
Conformer ensemble — overlay all frames from a multi-frame XYZ trajectory, with palette colouring and opacity control
Convex hull — semi-transparent facets over selected atoms (e.g. aromatic ring carbons, coordination spheres); optional hull-edge lines
Depth fog and gradients — 3D depth cues without needing a 3D viewer
Cheminformatics formats — mol, SDF, MOL2, PDB (with CRYST1 unit cell), SMILES (3D embedding via rdkit), and CIF (via ase) — bond connectivity read directly from file
Crystal / periodic structures — render periodic structures with unit cell box, ghost atoms, and crystallographic axis arrows (a/b/c); extXYZ Lattice= auto-detected; VASP/QE via phonopy
Multiple output formats — SVG (default), PNG, PDF, and GIF from the same command

Preconfigured but extensible. Built-in presets (default, flat, paton, skeletal, bubble, tube, wire) cover common use cases. Every setting — colors, radii, bond widths, gradients, fog — can be overridden via CLI flags or a custom JSON config file.

xyzrender caffeine.xyz                          # SVG with sensible defaults
xyzrender ts.out --ts -o figure.png             # TS with dashed bonds as PNG
xyzrender caffeine.xyz --gif-rot -go movie.gif  # rotation GIF for slides

See web app by @BNNLab xyzrender-web.streamlit.app.

Installation

pip install xyzrender

Or with uv:

uv tool install xyzrender

To test without installing, you can use uvx

uvx xyzrender

From Source:

Using pip:

git clone https://github.com/aligfellow/xyzrender.git
cd xyzrender
pip install .
# install in editable mode
pip install -e .
# or straight from git
pip install git+https://github.com/aligfellow/xyzrender.git

For more information on installation and optional dependencies (crystal, SMILES, CIF, GIF), see the installation docs

Quick start

xyzrender caffeine.xyz                                    # render XYZ → SVG
xyzrender calc.out                                        # QM output (ORCA, Gaussian, etc.)
xyzrender caffeine.xyz -o render.png                      # explicit output path/format
xyzrender caffeine.xyz --config paton --hy -o styled.svg  # preset + show hydrogens
xyzrender sn2.out --ts --hy -o ts.svg                     # auto-detect TS bonds
xyzrender caffeine.xyz --gif-rot -go caffeine.gif         # rotation GIF

Python API

from xyzrender import load, render, render_gif

mol = load("caffeine.xyz")
render(mol)                          # displays inline in Jupyter
render(mol, output="caffeine.svg")   # save as SVG/PNG/PDF

render(mol, config="paton", hy=True) # all CLI flags as kwargs
render_gif(mol, gif_rot="y")         # rotation GIF

For the full Python API (render options, build_config(), measure(), load() kwargs, return types), see the Python API guide or the runnable examples/examples.ipynb notebook.

Feature gallery

Presets

| Default | Flat | Paton (pymol-like) | Skeletal | |---------|------|--------------------|----------| | default | flat | paton | |

| Bubble | Tube | Wire | |--------|------|------| | bubble | tube | wire |

Style regions

| Tube + ball-stick region | Tube + ball-stick, NCI, vdW | |--------------------------|------------------------| | region | bimp regions |

Display options

| All H | Some H | No H | Aromatic | Kekule | |-------|--------|------|----------|--------| | all H | some H | no H | benzene | kekule |

vdW spheres

| All atoms | Partial | Paton-style | |-----------|---------|-------------| | vdw | vdw partial | vdw paton |

Convex hull

| Benzene ring | Anthracene rings | Auto rings | Rotation | |--------------|------------------|------------|----------| | benzene hull | anthracene hull | mnh hull | anthracene rot |

Highlight & molecule color

| Default (orchid) | Custom colour | Multi-group | Mol color + highlight | |------------------|---------------|-------------|-----------------------| | | hl custom | multi hl | mol color hl |

Depth of field

| DoF | Rotation | |-----|----------| | dof | dof |

Structural overlay & ensemble

| Overlay | Custom colour | Ensemble (CPK) | Ensemble (spectral) | |---------|---------------|----------------|---------------------| | overlay | overlay custom | | ensemble custom |

Transition states & NCI

| Auto TS | Manual TS | Auto NCI | QM output | |---------|-----------|----------|-----------| | | ts man | nci | bimp |

Annotations & labels

| Distances + angles + dihedrals | Custom labels | TS with labels | |--------------------|--------|----------------| | | ![labels](examples/images/caffeine_labels

Xyzrender

Install / Use

README