astr400
uv project template

Using uv for astrophysics projects

uv is an alternative to Conda: a lightweight, reproducible Python environment for notebooks and analysis scripts. Use Python 3.12+, keep the project as an environment rather than a published library, and rely on uv for dependency management and execution.

Overview

This pattern is designed for:

Install uv

Install uv before creating a project environment. The official install guide is the Astral uv installation page.

macOS

brew install uv

If you do not use Homebrew, the official installer also works:

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

Linux

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

After installation, open a new terminal or reload your shell so the uv command is in your PATH.

Windows (WSL 2)

Install uv inside your WSL 2 Linux environment rather than in PowerShell:

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

Then reopen the terminal and verify:

uv --version

.
├── data/
├── notebooks/
├── scripts/
├── README.md
├── pyproject.toml
├── uv.lock
└── .gitignore

Quick start

uv init astrolab --python 3.12 --bare --no-readme
cd astrolab
uv add astropy ipykernel jupyterlab matplotlib pandas scipy sympy
uv add --dev pytest ruff
uv sync

Run notebooks

uv run jupyter lab

Run tests

uv run pytest

Lint the project

uv run ruff check .

Run a script

uv run python scripts/example.py

VS Code kernel integration

To make the environment available as a Jupyter kernel in VS Code:

uv run python -m ipykernel install --user --name astrolab

Then in VS Code:

  1. Open a notebook.
  2. Click the kernel selector in the top-right corner.
  3. Choose astrolab or select the project interpreter at .venv/bin/python.
  4. Verify the kernel is correct with:
import sys
print(sys.executable)

This should point to the project-local environment, typically under .venv/bin/python.

Project configuration pattern

A typical pyproject.toml for this workflow looks like:

[project]
requires-python = ">=3.12"

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.3.0",
]

[tool.uv]
package = false

This keeps the project as a managed environment rather than an installable package.

Verification checklist

After setup, confirm the environment works with:

uv sync
uv run python -c "import astropy, matplotlib, pandas, scipy, sympy; print('ok')"
uv run jupyter lab --version
uv run pytest -q
uv run ruff check .

Notes