Install

Download prebuilt packages

Visit the Orbitron releases page and download the assets for your platform:
- macOS: Orbitron.Viewer.dmg (or Orbitron.Viewer.tar.gz) holds only Orbitron Viewer.app — the desktop viewer. GitHub rewrites the spaces in the asset name to dots; the app inside keeps its spaces. The command-line tool ships separately as orbitron-macos.zip.
- Windows: orbitron-windows.zip contains orbitron-viewer.exe and orbitron.exe alongside their runtime DLLs.
- Linux: two bare binaries, attached individually rather than as an archive — orbitron-viewer-linux and orbitron-linux (chmod +x them after downloading).
Drag Orbitron Viewer.app to /Applications on macOS. Place the command-line binaries somewhere on your PATH (e.g., /usr/local/bin, ~/bin, or %USERPROFILE%\AppData\Local\Programs\Orbitron). Double-click Orbitron Viewer.app or run orbitron --help in a terminal to confirm the installation.

Binary naming clarification: - GUI standalone: orbitron-viewer (built from ui/shell crate, launched by double-clicking app icon) - CLI tool: orbitron (command-line interface; orbitron view <file> prints a text summary, and orbitron view <file> --tui opens the terminal viewer). It does not link the desktop GUI — that’s the separate orbitron-viewer download. - macOS app bundle: Orbitron Viewer.app (wraps orbitron-viewer for macOS desktop integration) - Terminal UI: built into the orbitron binary, reached with orbitron view --tui (not a separate download)

System requirements

GPU: Metal (macOS), Vulkan (Linux), or DirectX 12 (Windows) for the desktop viewer. CLI/TUI binaries run headless; the viewer can fall back to OpenGL with WGPU_BACKEND=gl.
Optional: install maturin if you plan to rebuild the Python bridge locally.

For source builds, cargo run workflows, and contributor tooling, see the Developer Guide.

Python Package Installation

From Wheels (Recommended)

Each release attaches a cp310-abi3 wheel per platform (one build runs on CPython 3.10+). Install directly from the release URL — no Rust/HDF5 needed:

# Linux
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.8.0/orbitron-0.8.0-cp310-abi3-manylinux_2_28_x86_64.whl
# macOS (Apple Silicon)
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.8.0/orbitron-0.8.0-cp310-abi3-macosx_11_0_arm64.whl
# Windows
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.8.0/orbitron-0.8.0-cp310-abi3-win_amd64.whl

Platform wheels (all cp310-abi3): - Linux: *-manylinux_2_28_x86_64.whl - macOS Apple Silicon: *-macosx_11_0_arm64.whl - Windows: *-win_amd64.whl - macOS Intel: not published — build from source.

Orbitron is not currently published on PyPI. Install a release wheel from the URL above; pip install orbitron will not install this project until a PyPI release is announced.

Verify installation:

from orbitron import Orbitron
orb = Orbitron()
print("Orbitron installed successfully!")

From Source

If wheels are not available for your platform, use the repository’s conda setup so Rust, HDF5, Python, and the viewer build tools stay aligned:

./scripts/setup-conda-env.sh
(cd viewer/wasm/ts && npm ci)
conda run --no-capture-output -n orbitron-dev \
  python -m pip install -e extensions/python-bridge

The npm ci step installs the JavaScript build tools that the asset staging script (extensions/python-bridge/scripts/stage_viewer_assets.sh) calls with npm run build; the conda setup script does not run it. The editable install runs the PEP 517 backend and stages both the WASM viewer and widget assets. For Python-only iteration after that first build, see the Python binding development notes.

Jupyter Notebook Setup

For Jupyter integration:

pip install jupyter ipywidgets
jupyter notebook extensions/python-bridge/examples/orbitron_tutorial.ipynb

See §7 Python Bridge for complete API reference and examples.

Web Viewer Installation

For embedding the molecular viewer in websites or presentations:

Hosted viewer

The quickest path needs no Python: each release attaches orbitron-viewer-web-v<version>.zip, which unpacks to the same runtime files ready to drop on a static host.

Otherwise, install the Python wheel, then copy its orbitron.viewer_assets directory to your static host. Place .orbpack scenes beside it and point one iframe per scene at index.html?scene=.... Source builds stage the same four runtime files with extensions/python-bridge/scripts/stage_viewer_assets.sh.

See §10 Web Viewer Embedding for complete integration guide.

Self-contained HTML

Use File → Export → Export Web View… in the desktop app, orbitron web run.out -o viewer.html from the command line, or orbitron.export_html(scene_or_bundle, "viewer.html") in Python. The output contains the runtime and scene in one file. Reveal.js and Marp can load it in an iframe. For PowerPoint, link to the HTML or use a PNG fallback; the embedding guide explains the host-application limits.