---

This is a modern Cookiecutter template that can be used to initiate a Python project with all the necessary tools for development, testing, and deployment. It supports the following features:

• uv for dependency management
• Supports src layout
• CI/CD with GitHub Actions
• Pre-commit hooks with pre-commit
• Code quality with ruff, mypy, wemake-python-styleguide, deptry and prettier
• Publishing to PyPI by creating a new release on GitHub
• Testing and coverage with pytest and codecov
• Documentation with Docusaurus
• Compatibility testing for multiple versions of Python with tox-uv
• Containerization with Docker
• Development environment with VSCode devcontainers

---

Documentation - Example

---

Quickstart

Navigate to the directory where you want your new project and run:

uvx spinup-py my-project

Or install globally first:

uv tool install spinup-py
spinup-py my-project

Follow the guided prompts to configure your project. Once complete, a new directory my-project/ will be created with everything set up.

To retrofit an existing project with the latest tooling:

spinup-py --update /path/to/existing-project

spinup-py is the Python sibling of spinup-ts, the equivalent TypeScript project scaffolder.

Install from source

For local or development use (e.g. running it as a Claude Code plugin), install the checkout directly with an editable install:

uv tool install --editable .

Usage

# Scaffold a new project (bare form — positional name)
spinup-py my-project

# Same thing via the explicit subcommand
spinup-py new my-project

# Retrofit an existing project with the current tooling
spinup-py update /path/to/existing-project

# Or via the root flag (equivalent to `update`)
spinup-py --update /path/to/existing-project

# Print the installed version
spinup-py --version

Flags

Flag / command	Description
spinup-py <name>	Scaffold a new project with the given name (runs the guided prompts).
spinup-py new [<name>]	Explicit subcommand for scaffolding a new project.
spinup-py update [<dir>]	Retrofit an existing project at <dir> (defaults to the current directory).
--update, -u <dir>	Root-level equivalent of update — retrofit an existing project at <dir>.
--non-interactive, -y	Scaffold with sensible defaults and no prompts.
--version, -v	Print the installed version and exit.

Offline / custom template

By default the published CLI fetches its Cookiecutter template from GitHub (gh:joeblackwaslike/spinup-py). To use a local or custom template instead — handy when working offline or from a fork — set the SPINUP_PY_TEMPLATE environment variable to any Cookiecutter reference (a local path, a different GitHub repo, etc.):

SPINUP_PY_TEMPLATE=/path/to/template spinup-py my-project

Acknowledgements & Lineage

• This project is partially based on Florian Maas's great cookiecutter-uv repository. Many additional improvements have been added from all the projects I've worked on over the last 12 years or so.
• Florian also credits Audrey Feldroy's great cookiecutter-pypackage repository.

Feedback and contributing

My mission with this is to build the best project starter for python projects that has everything you can want, the ability to customize and/or opt out of most everything, and save you the most time!

I am only one person with very specific preferences. If you have any feedback you can email me at me@joeblack.nyc. If you find any bugs, mistakes, missed opportunities, or would like to contribute new functionality in any way, I would love to hear about it in an issue, feel free to email me the issue to get my attention.

This project is under continuous iterative improvements as I find bugs, and better and more effective ways to do things. But I can only do so much on my own, so please open an issue if you want to help/contribute and we can iterate and discuss how we can make this happen. If you find an outright bug or mistake, just open a PR and describe all the details there.