Installation¶

Goal: get a working openauc and confirm it runs.

Prerequisites¶

Python 3.11, 3.12 or 3.13. These are the versions declared in pyproject.toml (requires-python = ">=3.11,<3.14") and the three legs of the CI matrix.
uv for the development workflow.

Not published to PyPI

openauc is at version 0.1.0a1 and has not been released. Do not run pip install openauc — it will not install this project. Use one of the three paths below.

1. Development installation from a clone (recommended)¶

Run these from wherever you keep source checkouts:

git clone https://github.com/ronfinn/openauc-io.git
cd openauc-io
uv sync --all-groups

uv sync --all-groups creates .venv/ and installs the runtime dependencies plus the dev and docs groups. Confirm it worked — run this from the repository root:

uv run openauc version

Expected output:

0.1.0a1

This is an editable installation: edits to src/openauc/ take effect immediately, with no reinstall.

2. Installation from a locally built wheel¶

Use this to install into an environment that is not the repository's own — for a notebook, a separate project, or to check what a real user would get.

From the repository root:

uv build

That writes two files into dist/:

dist/openauc-0.1.0a1-py3-none-any.whl
dist/openauc-0.1.0a1.tar.gz

Then, from wherever you want the environment:

uv venv
uv pip install /path/to/openauc-io/dist/openauc-0.1.0a1-py3-none-any.whl

For example, if the clone is at ~/src/openauc-io:

uv pip install ~/src/openauc-io/dist/openauc-0.1.0a1-py3-none-any.whl

Confirm:

.venv/bin/openauc version

3. Editable installation into an existing environment¶

If you already have a virtual environment and want to develop against the source tree:

uv pip install --python /path/to/existing/.venv/bin/python \
  --editable /path/to/openauc-io

What gets installed¶

Runtime dependencies: pydantic, numpy, xarray, pandas, PyYAML, matplotlib, typer. The package ships a py.typed marker, so type checkers see its annotations.

The openauc console script is installed with the package.

Verifying the installation¶

uv run openauc version      # prints 0.1.0a1
uv run openauc formats      # lists aucx, generic-long, generic-wide

import openauc
print(openauc.__version__)          # '0.1.0a1'
print([f.format_id for f in openauc.available_formats()])
# ['aucx', 'generic-long', 'generic-wide']

Common failure modes¶

Symptom	Cause	Fix
`command not found: openauc`	Not using the project environment	Prefix with `uv run`, or activate `.venv`
`No such command 'generate'`	Older checkout without the synthetic generator	`git pull` then `uv sync --all-groups`
`ModuleNotFoundError: openauc`	Wheel not installed in the active environment	Re-run the wheel install, check `which python`

Next step¶

Five-minute quickstart — a full workflow with no input files.