Skip to main content

​
Installation

pyrig works with any Python 3.12+ project. Follow these steps to add pyrig to a new or existing project.
1

Create or navigate to your project

Start with an empty directory or navigate to an existing Python project:
mkdir my-project
cd my-project
2

Initialize with uv (recommended)

uv init
This creates a basic Python project structure with a pyproject.toml file.
3

Add pyrig as a dependency

uv add pyrig
4

Initialize your pyrig project

Run the initialization command:
uv run pyrig init
The init command runs a comprehensive setup sequence:
  1. Initializes git repository (git init)
  2. Adds development dependencies (pytest, ruff, etc.)
  3. Syncs the virtual environment
  4. Creates all config files and project structure
  5. Generates test skeletons
  6. Installs pre-commit hooks
  7. Formats and lints all files
  8. Runs the test suite
  9. Creates initial git commit
Duration: Typically 30-60 seconds depending on your machine.
The init command is idempotent. You can run it again anytime to sync your project structure.

​
Verify Installation

After installation completes, verify everything works: 
uv run pyrig version
# Output: pyrig version 10.2.3

​
Your First pyrig Command

Let’s explore what pyrig created by running a few commands:

​
View Generated Structure

tree -L 3 -I '__pycache__|*.pyc'
You should see: 
my-project/
├── my_project/
│   ├── __init__.py
│   ├── main.py
│   ├── rig/
│   │   ├── builders/
│   │   ├── cli/
│   │   ├── configs/
│   │   ├── tools/
│   │   └── tests/
│   └── src/
├── tests/
│   ├── conftest.py
│   └── fixtures/
├── .github/
│   └── workflows/
├── pyproject.toml
├── .gitignore
└── README.md

​
Try the Automatic CLI

Your project now has a working CLI. Try these commands: 
uv run my-project --help

​
Common Commands

Here are the most frequently used pyrig commands:
Full project initialization
uv run pyrig init
Transforms a basic Python project into a fully-configured, production-ready pyrig project. Safe to run on existing projects — it’s idempotent.
Create or update all config files
uv run pyrig mkroot
Discovers all ConfigFile subclasses and validates them. Creates missing files, adds missing keys, but preserves your customizations.
Generate test skeletons
uv run pyrig mktests
Creates test files mirroring your source structure. Non-destructive — only adds new test skeletons.
Create missing init.py files
uv run pyrig mkinits
Scans for namespace packages and creates minimal __init__.py files.
Build artifacts
uv run pyrig build
Runs all registered builders (PyInstaller executables, etc.).

​
Working Example

Let’s create a simple CLI tool to see pyrig in action.
1

Create a command function

Edit my_project/rig/cli/subcommands.py and add:
my_project/rig/cli/subcommands.py
def greet(name: str = "World") -> None:
    """Greet someone by name."""
    print(f"Hello, {name}!")
2

Run your command

uv run my-project greet --name Alice
# Output: Hello, Alice!
3

Add a shared command

Shared commands work across all dependent projects. Edit my_project/rig/cli/shared_subcommands.py:
my_project/rig/cli/shared_subcommands.py
import typer

def info() -> None:
    """Display project information."""
    typer.echo("My amazing pyrig project")
Now any project that depends on my-project will have the info command available.

​
Next Steps

Understand the Architecture

Learn how pyrig’s config system, CLI discovery, and multi-package inheritance work

Explore the CLI

Deep dive into CLI commands and automatic command discovery

Config System

Create custom config files and override existing ones

Testing

Learn about autouse fixtures and test infrastructure

​
Verbosity Control

All pyrig commands support flexible logging: 
uv run pyrig mkroot

​
Troubleshooting

Make sure you’re running commands with uv run:
uv run pyrig --help
Or activate your virtual environment:
source .venv/bin/activate  # Unix
.venv\Scripts\activate     # Windows
pyrig --help
Some pyrig commands require dev dependencies. Make sure they’re installed:
uv sync --all-groups
If pre-commit hooks fail to install:
chmod +x .git/hooks/pre-commit
pyrig requires Python 3.12+. Check your version:
python --version
If needed, specify the Python version for uv:
uv venv --python 3.12
The pyrig init command will create a git commit. Make sure any important uncommitted changes are stashed first.

​
What’s Next?

Now that you have pyrig running, dive deeper into the architecture to understand how the system works and how to extend it for your needs.

Build docs developers (and LLMs) love

Get started for freeTalk to us