Home

Installing climakitae

climakitae is a Python toolkit for climate data analysis from the Cal-Adapt Analytics Engine. This guide covers four installation paths depending on how you intend to use it.

0. Choosing an environment manager

Pick one of the following:

• uv — recommended. Fast, reproducible, works best on Linux. Some Windows and macOS users have reported friction with native scientific dependencies.
• conda / mamba — recommended for Windows and macOS users and anyone who has had trouble building native dependencies with pip/uv. Conda handles geospatial binaries (GDAL, PROJ, etc.) cleanly across platforms.

All examples below show both uv and conda variants. Pick the one that matches your setup and ignore the other.

Requirements

• Python 3.12 or 3.13
• Git (for the power-user and developer installs)

---

1. Casual install — "I just want to use it"

Note

Changes to the repository will only be picked up when the development team pushes a new release to PyPi. Local changes and changes to the main branch on github will not be reflected in your build.

For users who want to import climakitae in scripts or notebooks and never touch its source code.

With uv

uv venv --python 3.13
source .venv/bin/activate
uv pip install climakitae

With conda

conda create -n climakitae python=3.13 -y
conda activate climakitae
pip install climakitae

Verify

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

When (and How) to Update

A new release for climakitae is deployed every 2 months or by user request, whichever comes first. Every month or so you should reinstall or force upgrade the package with:

uv pip install -U climakitae

or

conda activate climakitae
pip install -U climakitae

to bring the latest changes into your environment.

---

2. Power-user install — "I want to modify the code"

Note

Changes to the repository will be picked up immediately when you (the user) change the code, or when you (the user) pull updates down from the main branch on github.

For users who want to clone the repo, edit source, and have their changes picked up immediately — but who aren't writing tests.

This uses an editable install: Python imports climakitae directly from your working tree, so edits take effect on the next import without reinstalling.

git clone https://github.com/cal-adapt/climakitae.git
cd climakitae

With uv

uv venv --python 3.13
source .venv/bin/activate
uv pip install -e .

With conda

conda create -n climakitae python=3.13 -y
conda activate climakitae
pip install -e .

Verify

python -c "import climakitae; print(climakitae.__file__)"
# Should print a path inside your cloned repo, not site-packages/

When (and How) to Upgrade:

climakitae is under active development and changes to main happen daily. Power users should check at the start of every new session whether there are changes to pull with:

git status
git pull

If you've made local changes that will be overwritten by a git pull you'll need to git stash them first. Once you've pulled the latest changes, they will be automatically be picked up in your install. If you're having problems with changes not being picked up check for environment conflicts with multiple installs. These can usually be resolved with:

uv pip uninstall climakitae
uv pip install -e . --no-deps

or

conda activate climakitae
pip uninstall climakitae
pip install -e . --no-deps

---

3. Developer install — "I'm modifying the code AND writing tests"

For contributors who will run the test suite, format code, and submit pull requests. This installs the optional dev dependency group (pytest, pytest-cov, pytest-xdist, black, isort, cftime) on top of the editable install.

git clone https://github.com/cal-adapt/climakitae.git
cd climakitae

With uv

uv venv --python 3.13
source .venv/bin/activate
uv pip install -e ".[dev]"

If you plan to build the documentation locally as well, install both extras: uv pip install -e ".[dev,docs]"

With conda

conda create -n climakitae python=3.13 -y
conda activate climakitae
pip install -e ".[dev]"

Verify

# Run the basic test suite (skips tests that require network access)
pytest -n auto -m "not advanced" --no-header -q

# Check formatters are available
black --version
isort --version

Pre-commit formatting hook (optional but recommended)

pip install pre-commit
pre-commit install

---

Troubleshooting

Symptom	Likely cause	Fix
pip install fails building geopandas, rioxarray, or pyproj	Missing native GDAL/PROJ libraries	Switch to the conda path — it ships these binaries prebuilt
uv not found	Not installed	Follow the uv install guide
Editable install ignored	Activated the wrong environment	Re-run source .venv/bin/activate (uv) or conda activate climakitae
Tests fail with network errors	You're running advanced tests	Use -m "not advanced" — advanced tests require S3 access

---

Quick reference

Use case	Command
Casual user (uv)	uv pip install climakitae
Casual user (conda)	pip install climakitae (in a conda env)
Power user	uv pip install -e .
Developer	uv pip install -e ".[dev]"
Developer + docs	uv pip install -e ".[dev,docs]"