📦 Installation Guide¶

“The best time to plant a tree was 20 years ago. The second best time is now.” — Chinese Proverb

Here’s how to install and set up the Seedling template so you can spend more time coding and less time duct-taping tools together. 🌱

🧰 Prerequisites¶

Required¶

Python 3.11+ — Modern features + type hints
Git — Version control
Copier — Template engine (we’ll install it)

Recommended¶

uv — Fast Python package manager
Nox — Task automation
Just — Shortcut-friendly command runner (optional but addictive)

Optional¶

pyenv — Python version management
GitHub CLI — For easy repo wrangling

🔧 Installing Required Tools¶

1 — Install uv (recommended)¶

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

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

# pip fallback
pip install uv

2 — Install Copier¶

# With uv (recommended)
uv pip install copier

# With pip
pip install copier

# With pipx (isolated)
pipx install copier

3 — Install Nox (recommended)¶

# With uv
uv pip install nox

# With pip
pip install nox

# With pipx
pipx install nox

4 — Install Just (optional, but highly recommended)¶

# macOS
brew install just

# Linux
# Download from https://github.com/casey/just/releases or use your package manager

# Windows
choco install just

🌟 What the Template Provides¶

✅ Already Included¶

Python deps: Black, Ruff, MyPy, pytest, Hypothesis, Sphinx…
Pre-commit hooks
Nox automation tasks
Just command shortcuts
GitHub Actions workflows

🔧 You Install¶

Copier — Project generator
uv — Dependency manager
Nox — Automation runner
Just — Command runner (optional)

✅ Verify Installation¶

copier --version
uv --version
nox --version
just --version   # optional

You should see version numbers (not error messages).

⚡ Quick Install Script¶

curl -LsSf https://raw.githubusercontent.com/jeffrichley/seedling/main/scripts/install-tools.sh | bash

What it does:

Installs uv, Copier, Nox, Just
Checks existing installs
Prints next steps with pretty colors ✨

🛠️ Development Environment Setup¶

1 — Clone the Repo¶

git clone https://github.com/jeffrichley/seedling.git
cd seedling

2 — Python Environment¶

# pyenv
yenv install 3.11.0 && pyenv local 3.11.0

# uv
uv sync

3 — Dev Dependencies¶

uv sync --all-extras
# OR
pip install -e ".[dev]"

4 — Pre-commit Hooks¶

pre-commit install

🧪 Test the Installation¶

1 — Generate Test Project¶

copier copy . /tmp/test-project --trust
cd /tmp/test-project

2 — Verify¶

uv sync
nox -s tests
just quality

3 — Clean Up¶

rm -rf /tmp/test-project

🛠️ Troubleshooting¶

Copier not found — pip install copier
uv missing — curl -LsSf https://astral.sh/uv/install.sh | sh
Nox missing — pip install nox
Just missing — install from GitHub releases or your package manager
Python too old — must be 3.11+
Permission errors — use --user flag or a venv

See:

🌱 Next Steps¶

Generate your first project → 🚀 Quick Start Guide
Learn configuration → ⚙️ Configuration Guide
Explore examples → 📚 Examples
Customize the template to your needs