uvi - The Future of Python Project Generation

UVI is a modern Python project generator built around UV - the high-performance Python package manager that's reshaping the Python ecosystem. This tool creates fully-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

Why UV is the Way Forward

UV represents the future of Python dependency management:

• Blazing Fast: UV is up to 10-100x faster than traditional tools
• Reliable and Deterministic: Produces perfectly reproducible environments
• Modern Architecture: Built in Rust with best practices from the ground up
• Complete Solution: Handles all Python packaging needs in one tool

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
• Future-ready: Your project starts with tomorrow's best practices today

Future Plans

UVI builds upon the excellent foundation established by Cookiecutter, which it currently uses as its template engine. While honoring this heritage, UVI continues to evolve with a focus on enhanced performance, simplified workflows, and deeper integration with the broader UV ecosystem.

As UV reshapes the Python tooling landscape, UVI will remain at the forefront of modern Python project generation, bringing the best practices of both worlds together while pursuing its own technical path forward.