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

uvx uvtemplate create

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

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

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.

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.

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

Start the interactive wizard:

uvx uvtemplate create

Skip git setup (just create the project files):

uvx uvtemplate create --skip-git

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

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

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

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.

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.

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

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.

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.

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.

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.