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, quantum chemistry input or output — from the command line or from Python/Jupyter.

xyzrender turns molecular structures into clean vector SVG graphics — plus PNG, PDF, and animated GIF — ready for papers, presentations, and supporting information. It reads XYZ, mol/SDF, MOL2, PDB, SMILES, CIF, cube files, and QM input/output files from Gaussian, ORCA, NWChem, Q-Chem, Psi4, MOPAC, GAMESS, Turbomole, and periodic codes (VASP, Quantum ESPRESSO, SIESTA, ABINIT, CP2K). 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 automatic TS / NCI bond detection. Orientation control is available through an interface to v by Ksenia Briling @briling.

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
Stereochemistry labels — R/S, E/Z, axial, planar (metallocene and CIP), and helical chirality labels detected and annotated automatically via xyzgraph
Non-covalent interactions — hydrogen bonds and other weak interactions shown as dotted lines, detected automatically via xyzgraph
Bond display rules — selectively hide or add bonds using element categories (M, sbm, L, het), element pairs (M-L, Fe-het), pi-coordination (M-pi), or atom indices; haptic mode replaces pi-coordination fans with single centroid bonds
Surfaces — molecular orbitals, electron density, ESP colormapping, NCI surfaces, and vdW spheres; solid, mesh, contour, wire, and dot styles
Styling — highlight & molecule color, radius scaling (by element, category, or index), per-atom fill opacity (bond-agnostic), style regions, atom property colormaps with colorbar, and depth-of-field / depth-fog effects
Annotations — distances, angles, dihedrals, custom labels, atom indices, and 3D vector arrows (dipoles, forces, fields)
Structural overlay — RMSD-align two structures and render in contrasting colours; works across different atom counts via automatic scaffold detection. Independent style overrides (atom/bond size, stroke, opacity, per-overlay bond rules), and --no-align to skip alignment when geometries already share a frame
Conformer ensemble — overlay all frames from a multi-frame XYZ trajectory, with palette colouring and opacity control
Convex hull, hull faces & pores — semi-transparent facets over selected atoms or rings, exposed faces of molecular cages, and pore rendering
GIF animations — rotation, TS vibration, trajectory, diffuse/assembly, and depth-of-field animations
Input formats — XYZ, mol/SDF, MOL2, PDB, SMILES, CIF, cube files, and QM input/output from Gaussian, ORCA, NWChem, Q-Chem, Psi4, MOPAC, GAMESS, Turbomole, CP2K, VASP, Quantum ESPRESSO, SIESTA, and ABINIT
Crystal / periodic structures — unit cell box, ghost atoms, supercells, and crystallographic axis arrows; auto-detected from VASP POSCAR, QE pw.in, SIESTA FDF, ABINIT, CP2K, and extXYZ Lattice= headers
Multiple output formats — vector SVG (default), PNG, PDF, and GIF — all from the same command

Preconfigured but extensible. Built-in presets (default, flat, paton, skeletal, bubble, tube, mtube, btube, wire, graph) 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
# latest development version:
pip install --upgrade git+https://github.com/aligfellow/xyzrender.git

Or with uv:

uv tool install xyzrender
# latest development version:
uv tool install git+https://github.com/aligfellow/xyzrender.git

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 caffeine.xyz --config pmol --hy -o pmol.svg     # ball-and-stick + element-coloured bonds
xyzrender caffeine.xyz --config graph -o graph.svg        # minimalist graph-style rendering
xyzrender sn2.out --ts --hy -o ts.svg                     # auto-detect TS bonds
xyzrender caffeine.xyz --gif-rot -go caffeine.gif         # rotation GIF
xyzrender caffeine.xyz --gif-bounce 50 -go caffeine_bounce_50.gif  # bounce GIF (±50°)
xyzrender caffeine.xyz --glow "N,O" --glow-strength 4 -o glow.svg  # atom glow

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)	Pmol

Skeletal	Bubble	Tube	BTube

Wire	Graph	MTube

MTube + `unbond pi`	`haptic`

Style regions

Tube + ball-stick region	Tube + ball-stick, NCI, vdW

Display options

All H	Some H	No H	Aromatic	Kekule

vdW spheres

All atoms	Partial	Paton-style

Convex hull

Benzene ring	Anthracene rings	Auto rings	Rotation

Hull faces & pore detection

Buckyball faces	Buckyball pore	MOF-5 faces	MOF-5 pore	MOF-5 combo	Rotation

Highlight & molecule color

Default (orchid)	Custom colour	Multi-group	Mol color + highlight

Single atom scaled (Co ×2)	Multi-group (N,O ×1.4 + H ×0.8)	Per-atom opacity + radius scale

Depth of field

DoF	Rotation

Glow

Glow (N,O atoms)

Structural overlay & ensemble

Overlay	Custom colour	Cross-molecule	Per-overlay style

Ensemble (CPK)	Ensemble (viridis)

Transition states & NCI

Auto TS	Manual TS	Auto NCI	TS + NCI custom colours	QM output

Annotations & labels

Distances + angles + dihedrals	Custom labels	TS with labels

Stereochemistry labels

Isothiourea (R/S, E/Z, planar)	TS with stereo (Mn-H₂, `--ts --stereo`)

Atom property colormap

Mulliken charges (rotation)	Symmetric range	With colorbar

Surfaces (cube files)

MO (HOMO)	MO (LUMO)	Density

ESP	ESP + colorbar	ESP + coolwarm	ESP fixed range (`±0.03`)

MO mesh	MO contour	MO dot	Density contour

NCI surface (H-bond)	NCI surface (pi-stack)	NCI mesh	Vector arrows

File formats

PDB	SMILES

Crystal / periodic structures

Unit cell	Rotation	VASP	Supercell 2×2×1	Viewing direction

GIF animations

Rotation	TS + NCI + vdW + rotation	Trajectory	TS

Bounce (50deg)

Overlay rotation	MO	Density

Vectors	Diffuse / assembly

For usage details and CLI commands, see the examples and CLI reference in the docs.

Documentation

Full documentation at xyzrender.readthedocs.io:

Installation — PyPI, uv, source, optional dependencies
CLI Quickstart — getting started from the command line
Python API Guide — render options, build_config(), measure(), return types
Examples — presets, overlays, surfaces, crystal, annotations, and more
Configuration — presets, custom JSON, styling flags
CLI Reference — all flags
Input Formats — XYZ, QM output, SDF, PDB, SMILES, CIF, cube files
API Reference — auto-generated from docstrings

License

MIT

Acknowledgements

The SVG rendering in xyzrender is built on and heavily inspired by xyz2svg. The CPK colour scheme, core SVG atom/bond rendering logic, fog, and overall approach originate from that project.

Ksenia Briling (@briling) — xyz2svg and v
Iñigo Iribarren Aguirre (@iribirii) — radial gradient (pseudo-3D) rendering from xyz2svg.

Key dependencies:

xyzgraph — bond connectivity, bond orders, aromaticity detection and non-covalent interactions from molecular geometry
graphRC — reaction coordinate analysis and TS bond detection from imaginary frequency vibrations
cclib — parsing quantum chemistry output files (ORCA, Gaussian, Q-Chem, etc.)
CairoSVG — SVG to PNG/PDF conversion
Pillow — GIF frame assembly
resvg-py — SVG to PNG conversion preserving SVG effects

Falls back to CairoSVG automatically (filters silently ignored). SVG output always contains the filters regardless.

Optional dependencies:

rdkit — SMILES 3D embedding (pip install 'xyzrender[smi]')
ase — CIF parsing, and ASE viewer integration (pip install 'xyzrender[cif]')
v — interactive molecule orientation (pip install xyzrender[v], Linux only, not included into [all])

Contributors:

Ksenia Briling (@briling) — vmol integration and the xyz2svg foundation
Sander Cohen-Janes (@scohenjanes5) — crystal/periodic structure support (VASP, Quantum ESPRESSO, ghost atoms, crystallographic axes), vector annotations and gif parallelisation, gaussian input parsing
Rubén Laplaza (@rlaplaza) — convex hull facets
Iñigo Iribarren Aguirre (@iribirii) — logo design, radial gradients respecting colour space (pseudo-3D), skeletal rendering, ensemble display, supercell projection, metal tube preset
James O'Brien (@JamesOBrien2) — stereochemistry detection and integration, nci/ts colour control, graph styling, pmol styling, colour palette extension, ase viewer integration, igmh cubes
Vinicius Port (@caprilesport) — v binary path discovery
Lucas Attia (@lucasattia) — transparent background

Citation

xyzrender uses xyzgraph and graphRC for all molecular graph construction — bond orders, aromaticity detection, NCI interactions, and TS bond detection. If you use xyzrender in published work, please cite:

A.S. Goodfellow* and B.N. Nguyen, J. Chem. Theory Comput., 2026, DOI: 10.1021/acs.jctc.5c02073. Preprint here.

BibTeX

@article{goodfellow2026xyzgraph,
  author  = {Goodfellow, A.S. and Nguyen, B.N.},
  title   = {Graph-Based Internal Coordinate Analysis for Transition State Characterization},
  journal = {J. Chem. Theory Comput.},
  year    = {2026},
  doi     = {10.1021/acs.jctc.5c02073},
}

Development

Information on dev setup and CI

Requires uv and just.

git clone https://github.com/aligfellow/xyzrender.git
cd xyzrender
just setup   # install dev dependencies
just check   # lint + type-check + tests

Command	Description
`just check`	Run lint + type-check + tests
`just lint`	Format and lint with ruff
`just type`	Type-check with ty
`just test`	Run pytest with coverage
`just fix`	Auto-fix lint issues
`just build`	Build distribution
`just setup`	Install all dev dependencies

CI

GitHub Actions runs lint, type-check, and tests on every push to main and every PR targeting main. Coverage is uploaded to Codecov.

Template

Generated from aligfellow/python-template.

Updating from the template

If this project was created with copier, you can pull in upstream template improvements:

# Run from the project root
copier update --trust

This will:

Fetch the latest version of the template
Re-ask any questions whose defaults have changed
Re-render the templated files with your existing answers
Apply the changes as a diff — your project-specific edits are preserved via a three-way merge

If there are conflicts (e.g. you modified the justfile and so did the template), copier will leave standard merge conflict markers (<<<<<<< / >>>>>>>) for you to resolve manually.

The --trust flag is required because the template defines tasks (used for git init on first copy). The tasks don't run during update, but copier requires trust for any template that declares them.

Requires that the project was originally created with copier copy, not the plain GitHub "Use this template" button.

Name		Name	Last commit message	Last commit date
Latest commit History 234 Commits
.github		.github
docs		docs
examples		examples
src/xyzrender		src/xyzrender
tests		tests
.copier-answers.yml		.copier-answers.yml
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.readthedocs.yaml		.readthedocs.yaml
CITATION.cff		CITATION.cff
LICENSE		LICENSE
README.md		README.md
justfile		justfile
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

xyzrender: Publication-quality molecular graphics.

Installation

From Source:

Quick start

Python API

Feature gallery

Presets

Style regions

Display options

vdW spheres

Convex hull

Hull faces & pore detection

Highlight & molecule color

Depth of field

Glow

Structural overlay & ensemble

Transition states & NCI

Annotations & labels

Stereochemistry labels

Atom property colormap

Surfaces (cube files)

File formats

Crystal / periodic structures

GIF animations

Documentation

License

Acknowledgements

Citation

BibTeX

Development

CI

Template

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Contributors

Uh oh!

Languages