Installation

This guide covers a development install (editable, with dev tooling). For a plain user install, see the Getting Started installation guide.

Prerequisites

• python >= 3.11
• Git
• (Optional) uv - A fast Python package installer and resolver

Check your Python version:

python --version

Development Installation

Step 1: Clone the Repository

git clone https://github.com/jaff-chemistry/jaff.git
cd jaff

Step 2: Create a Virtual Environment

It's strongly recommended to use a virtual environment for development:

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Create virtual environment with uv (much faster)
uv venv

# Activate
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Create conda environment
conda create -n .venv python=3.11

# Activate
conda activate .venv

Step 3: Install in Development Mode

Install JAFF in editable mode with all development dependencies:

pip install -e ".[dev]"

uv pip install -e ".[dev]"

The -e flag installs the package in "editable" mode, meaning changes you make to the source code are immediately reflected without reinstalling.

Verifying Your Development Setup

After installation, verify everything is working:

python -c "import jaff; print(jaff.__version__)"

jaffgen --help
jaffx --help

pytest

ruff check .

Dependencies

Core Dependencies

These are automatically installed with JAFF:

Development Dependencies

When installing with [dev], the following additional packages are installed:

Testing Tools

Documentation Tools

Updating Dependencies

After pulling new changes, refresh your editable install:

git pull
pip install -e ".[dev]" --upgrade

git pull
# uv automatically resolves to the latest compatible versions
uv pip install -e ".[dev]" --upgrade

Building Documentation

JAFF uses Zensical as a static site generator for the documentation.

# Serve with live reload (recommended during development)
zensical serve

# Build static site into site/
zensical build

# Build with strict link validation
zensical build --strict

# Deploy to GitHub Pages (maintainers only)
zensical gh-deploy

When serving, open http://127.0.0.1:8000. The site rebuilds automatically on save.

Working with uv (Recommended)

uv is a fast Python package installer and resolver written in Rust, significantly faster than pip.

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Common uv Commands

# Create virtual environment
uv venv

# Install a package
uv pip install <package_name>

# Install JAFF in editable mode
uv pip install -e ".[dev]"

# Run a command inside the virtual environment
uv run python script.py

IDE Setup

{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "editor.formatOnSave": true,
    "python.linting.enabled": true,
    "ruff.format.args": ["--config", "pyproject.toml"]
}

{
    "languages": {
        "Python": {
            "language_servers": ["pyright"],
            "format_on_save": true
        }
    },

    "python": {
        "interpreter": ".venv/bin/python"
    },

    "formatter": {
        "external": {
            "command": "ruff",
            "arguments": ["format", "--config", "pyproject.toml", "-"]
        }
    },

    "lint": {
        "external": {
            "command": "ruff",
            "arguments": ["check", "--config", "pyproject.toml", "-"]
        }
    }
}

Next Steps

• Running tests — see the Testing Guide.
• Code style and linting — see the Code Style Guide.
• Submitting changes — see the Contributing Guide.