uvi

UVI is a recent Python project generator built around UV - the fast Python package manager. This tool creates pre-configured Python projects with best practices and modern development tools already set up.

Table of Contents

• Quick Start
• Why UV is the Way Forward
• Features
• Pre-configured GitHub Workflows
• UVI's Self-Consistent Philosophy
• Documentation
• Project Benefits
• Future Plans

Quick Start

# Install UVI
uv tool install uvi

# Create a new project
uvi  # Answer a few simple prompts

# Navigate to your new project
cd your-project-name

# Start your documentation server
uv run mkdocs serve

This project is designed with UV as its foundation - UV is integrated into every aspect of the project architecture.

Note

UVI is under active development with new features being added regularly. See our progress tracker for details.

Features

• UV at the core: The foundation of our dependency management approach
• UV-powered testing: Compatibility testing with tox-uv
• Modern code quality: ruff (including Pylint-equivalent rules), mypy, deptry, and prettier
• CI/CD integration: Workflows with GitHub Actions
• Git hooks: Automated checks with pre-commit
• Testing: Framework with pytest and codecov
• Documentation: Generated with MkDocs
• Publishing: Easy PyPI publishing through GitHub releases
• Containerization: Development and deployment with Docker
• Dev environments: Consistent setup with VSCode devcontainers

Pre-configured GitHub Workflows

Projects created with UVI come with production-ready GitHub workflows:

• Comprehensive CI Pipeline: Runs quality checks, tests, and type checking with a single workflow
• Multi-Python Testing: Automatically verifies compatibility with Python 3.9-3.13 using matrix builds
• Documentation CI: Validates that your MkDocs documentation builds successfully
• Code Coverage: Seamlessly integrated with Codecov for visibility into test coverage
• Optimized Performance: Pre-configured caching for dependencies and pre-commit to speed up CI runs
• Custom GitHub Actions: Includes reusable custom actions for Python environment setup
• Conditional Features: Workflows adapt based on your project configuration (MkDocs, Codecov, etc.)

All workflows use the latest stable Ubuntu runners and leverage UV for consistent, fast dependency installation.

UVI's Self-Consistent Philosophy

UVI embodies a fundamentally consistent approach. The same technology, patterns, and workflows used to build UVI itself are automatically provided in every project UVI generates:

• Consistent Toolchain: The UV-powered build process that makes UVI lightning-fast is the same one your projects inherit
• Shared Infrastructure: The GitHub Actions workflows, pre-commit hooks, and testing frameworks aren't bolt-ons - they're the same ones UVI relies on
• Inherited DNA: When we improve UVI's internal architecture, your next project automatically benefits

This creates a consistent workflow:

1. You install UVI (one simple command)
2. You run UVI (answer a few prompts)
3. You get a project with the same capabilities, performance, and reliability as UVI itself

The value of UVI is in this consistency - generated projects benefit from the same technical foundations that power UVI itself.

Documentation

UVI features comprehensive documentation to help you get the most out of your projects:

• Full Documentation: Detailed guides and API reference
• Generated Docs: Each project comes with MkDocs-powered documentation
• Built-in Examples: Sample code and reference implementations included in every project
• Code Comments: Clear, meaningful comments throughout the codebase

Project Benefits

Projects created with UVI inherit significant advantages:

• Fast dependency installation: uv sync installs dependencies in seconds
• Reproducible environments: Lock files ensure consistent builds across machines
• Simplified workflow: Single command for environment setup