uvtemplate

A time-saving CLI tool to quickly start new Python projects with uv using the simple-modern-uv template.

Quick Start

For Humans (Interactive Mode)

uvx uvtemplate create

This will guide you through creating a new project step by step.

For AI Agents (Non-Interactive Mode)

AI coding agents like Claude Code can create projects programmatically:

uvx uvtemplate --yes --destination my-project \
  --data package_name=my-project \
  --data package_description="My awesome project" \
  --data package_author_name="Your Name" \
  --skip-git

Do I Need uv?

Yes. You will need to have uv installed. Read that page or my template docs for background on why uv is such an improved package manager for Python.

What is uvtemplate?

It’s the tool I wish I’d had when setting up projects with uv.

uvx uvtemplate create will clone a new project template and help you set up your GitHub repo. The template is tiny and sets up uv, ruff linting and formatting, GitHub Actions, publishing to PyPI, type checking, and more.

Usage

Commands

Options

Template Values

Use --data KEY=VALUE to set these values:

Examples

Interactive (Human) Usage

Start the interactive wizard:

uvx uvtemplate create

Skip git setup (just create the project files):

uvx uvtemplate create --skip-git

Non-Interactive (Agent) Usage

Create a complete project without any prompts:

uvx uvtemplate --yes --destination my-cli-tool \
  --data package_name=my-cli-tool \
  --data package_module=my_cli_tool \
  --data package_description="A command-line tool for doing things" \
  --data package_author_name="Claude" \
  --data package_author_email="ai@example.com" \
  --data package_github_org="myorg" \
  --skip-git

Create a project and set up a private GitHub repo:

uvx uvtemplate --yes --destination my-project \
  --data package_name=my-project \
  --data package_description="My project" \
  --data package_github_org="myorg"

Create a project with a public GitHub repo:

uvx uvtemplate --yes --destination my-project \
  --data package_name=my-project \
  --public

Using an Answers File

If you have a .copier-answers.yml from a previous project:

uvx uvtemplate --yes --destination new-project \
  --answers-file /path/to/existing/.copier-answers.yml

For AI Coding Agents

This tool is designed to work well with AI coding agents like Claude Code, Cursor, GitHub Copilot, etc.

Key Points for Agents

1. Use --yes flag: This auto-confirms all prompts, making the tool fully non-interactive.

2. Provide all values via --data: Set template values upfront to avoid interactive prompts.

3. Use --skip-git if you want to handle git setup separately or don’t need it.

4. The tool uses exit codes: 0 for success, 1 for failure/cancellation.

5. Values are derived intelligently: If you provide --destination my-project, the tool will automatically derive package_name=my-project and package_module=my_project unless you override them.

Minimal Agent Example

The simplest non-interactive usage:

uvx uvtemplate --yes --destination my-project --skip-git

This creates a project with sensible defaults derived from the destination name and your git/GitHub config.

Complete Agent Example

For full control:

uvx uvtemplate --yes --destination my-project \
  --data package_name=my-project \
  --data package_module=my_project \
  --data package_description="Project description here" \
  --data package_author_name="Author Name" \
  --data package_author_email="author@example.com" \
  --data package_github_org="github-org" \
  --skip-git

What Python Project Template Does it Use?

The simple-modern-uv template. See that repo for full docs and this thread for a bit more context.

The template includes:

• uv for project setup and dependencies

• ruff for modern linting and formatting

• GitHub Actions for CI and publishing workflows

• Dynamic versioning from git tags

• PyPI publishing workflows

• BasedPyright for type checking

• Pytest for tests

• Codespell for spell checking

If you prefer, you can use that template directly; uvtemplate is just a CLI wrapper.

If you have another copier-format template you want to use, specify it with --template.

Migrating an Existing Project

Use the migrate command to analyze an existing project and get migration recommendations:

cd my-existing-project
uvx uvtemplate migrate

This will detect your current build system (Poetry, setuptools, Pipenv, etc.) and provide a step-by-step guide for migrating to uv. It analyzes your project and outputs recommendations—it does not automatically modify any files.

The migrate command works well with AI agents, providing structured recommendations that an agent can follow to perform the migration.

Alternative: Manual Migration

You can also create a fresh template as a reference and manually copy what you need:

uvtemplate create --skip-git --destination .uvtemplate-ref

Then copy the relevant files (pyproject.toml structure, Makefile, workflows, etc.) into your existing project.

Updating a Project

Projects created with uvtemplate can be updated to the latest template version:

cd my-project
uvx uvtemplate update

This uses copier under the hood to apply template updates while preserving your customizations. The command will show you what changed and let you resolve any conflicts.

For non-interactive updates (useful for AI agents):

uvx uvtemplate update --yes

Note: The update command only works on projects that were created with uvtemplate (or copier directly). If you migrated a project manually, use uvtemplate migrate to see recommendations.

This project was (of course) built using simple-modern-uv.