Getting Started

Installation#

Python (Recommended)#

bash

pip install zsasa
# or
uv add zsasa

Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (x86_64). Python 3.11-3.13 supported.

The pre-built x86_64 wheels, CLI binaries and Docker image need a CPU with AVX2 and FMA (x86-64-v3: Intel Haswell or AMD Excavator, 2013 and later, including every Zen CPU). The macOS builds need macOS 11 or later. On an older CPU, build from source: pip install --no-binary zsasa zsasa (needs Zig 0.16) or zig build -Doptimize=ReleaseFast, which target the machine they run on.

For structure file support (mmCIF/PDB), install with an integration:

bash

pip install zsasa[gemmi]      # Gemmi (fast mmCIF/PDB parsing)
pip install zsasa[biopython]  # BioPython
pip install zsasa[biotite]    # Biotite
# or with uv
uv add zsasa[gemmi]

CLI#

bash

# Via pip/uv (bundled with the Python package)
pip install zsasa
# or
uv tool install zsasa

# One-line install (downloads pre-built binary)
curl -fsSL https://raw.githubusercontent.com/N283T/zsasa/main/install.sh | sh

# Or with custom install directory
curl -fsSL https://raw.githubusercontent.com/N283T/zsasa/main/install.sh | INSTALL_DIR=/usr/local/bin sh

# Or build from source (requires Zig 0.16.0)
git clone https://github.com/N283T/zsasa.git
cd zsasa
zig build -Doptimize=ReleaseFast

The binary is at ./zig-out/bin/zsasa (source build) or ~/.local/bin/zsasa (install.sh). The installer supports Linux and macOS. It downloads the latest release by default, or VERSION=X.Y.Z when pinned. If Zig 0.16.0 and git are available, it builds the tagged source release locally; otherwise it downloads the matching pre-built binary and verifies it against the release's SHA256SUMS.

The installer stops without installing when it cannot verify the binary: SHA256SUMS cannot be downloaded or has no entry for the binary, neither sha256sum nor shasum is installed, or the checksum differs. To install without verification anyway (not recommended), set SKIP_CHECKSUM=1:

bash

curl -fsSL https://raw.githubusercontent.com/N283T/zsasa/main/install.sh | SKIP_CHECKSUM=1 sh

Variable	Default	Description
`VERSION`	latest release	Version to install (`X.Y.Z`)
`INSTALL_DIR`	`~/.local/bin`	Absolute path of the install directory
`SKIP_CHECKSUM`	unset	Set to `1` to skip checksum verification of the downloaded binary

note

If you have both the standalone binary and the Python package installed, the one that appears first in your PATH will be used. To avoid confusion, use only one installation method for the CLI.

Homebrew (macOS / Linux)#

bash

brew tap N283T/zsasa
brew install zsasa

conda-forge#

bash

conda install -c conda-forge zsasa
# or
pixi add zsasa

zsasa is the Python package and brings the zsasa command with it. The command alone is zsasa-cli, and the shared library libzsasa. The platforms that are built are listed on anaconda.org.

The conda-forge packages are built for the baseline CPU of each platform, so they run on any x86-64 machine. The PyPI wheels and the release binaries need AVX2 and use wider vectors on x86-64; prefer them there when speed matters.

Docker#

bash

docker run --rm -v $(pwd):/data ghcr.io/n283t/zsasa calc /data/structure.cif /data/output.json

Scoop (Windows)#

powershell

scoop bucket add zsasa https://github.com/N283T/scoop-zsasa
scoop install zsasa

Nix#

bash

# Run directly
nix run github:N283T/zsasa -- calc structure.cif output.json

# Install to profile
nix profile install github:N283T/zsasa

First Calculation#

Python#

python

import numpy as np
from zsasa import calculate_sasa

# Two atoms with coordinates and van der Waals radii
coords = np.array([[0.0, 0.0, 0.0], [3.0, 0.0, 0.0]])
radii = np.array([1.5, 1.5])

result = calculate_sasa(coords, radii)
print(f"Total SASA: {result.total_area:.2f} Å²")
print(f"Per-atom: {result.atom_areas}")

With a structure file (mmCIF/PDB):

python

from zsasa.integrations.gemmi import calculate_sasa_from_structure

result = calculate_sasa_from_structure("protein.cif")
print(f"Total SASA: {result.total_area:.1f} Å²")

# Per-residue analysis
from zsasa import aggregate_from_result

for res in aggregate_from_result(result):
    print(f"  {res.chain_id}:{res.residue_name}{res.residue_id} = {res.total_area:.1f} Å²")

CLI#

bash

# Calculate SASA from a structure file
zsasa calc structure.cif output.json

# With atom classifier and per-residue output
zsasa calc --classifier=naccess --rsa structure.cif output.json

# CSV output
zsasa calc --format=csv structure.cif output.csv

What's Next?#

Choose the path that matches your workflow:

Goal	Next page
Decide between CLI and Python	Choosing CLI or Python
Process many structure files	Batch Processing
Make reproducible TOML workflows	Workflow Files
Understand atom radius assignment	Classifiers and CCD
Analyze MD trajectories	Trajectory Analysis
Look up command syntax	CLI Reference
Use Python bindings	Python API