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.

Alpha release

openauc 0.1.0a1 is published on PyPI as a pre-release. APIs and behaviour may change without notice. Because it is a pre-release, a bare pip install openauc will not install it — ask for the version explicitly, as below.

1. Installation from PyPI (recommended for users)¶

python -m pip install "openauc==0.1.0a1"

If you would rather take whatever the newest pre-release is, without naming a version:

python -m pip install --pre openauc

Confirm:

openauc version

Expected output:

0.1.0a1

That installs the published wheel — openauc-0.1.0a1-py3-none-any.whl — from the PyPI project page, together with the runtime dependencies listed below. The sdist, openauc-0.1.0a1.tar.gz, is published alongside it.

2. Development installation from a clone¶

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.

3. 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

4. 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.