protostar 0.10.2

---

Simple Python project scaffolding that understands your tools

---

| Get Started | Docs | Why Protostar? | Design Principles | Authoring Templates | Troubleshooting |

Pick your tools, and Protostar writes their configuration, hooks, and CI. When your template improves, updates merge into your files by meaning, so your edits stay.

Why Protostar?

Already know Cookiecutter or Copier? The detailed comparison runs the same template and the same update through both tools and compares them in more depth.

Plenty of tools can create a Python project. What sets Protostar apart is that it understands the tools it sets up and the files they live in, and that keeps everything simple:

• Say what you want, not how to build it. A template is a short list of the tools you want and the packages you need. Protostar writes every configuration file, commit hook, and CI step those tools require.

• Every tool is a switch. Want Docker but not direnv? Pass --docker --no-direnv. Change your mind a year later, and Protostar adds or removes that tool's setup cleanly.

• Updates that understand your files. When a template improves, Protostar merges the change into your project by meaning, not line by line. Your own edits stay, and if you and the update changed the same setting, you get one clear choice instead of a mess to untangle.

• Nothing breaks halfway. Protostar shows you every change before making it, and undoes everything if a step fails.

• Fits the project you already have, and runs from scripts, CI, and coding agents without stopping to ask questions.

In a terminal, protostar sync shows each conflict with both sides before anything is applied:

Protostar is Python-only and builds on uv. It's young, and it grows with the people using it: feature requests shape what comes next.

Get Started

Install Protostar with uv on any platform:

uv tool install protostar

Or with Homebrew on macOS:

brew install jacksonfergusondev/tap/protostar

Protostar needs uv and git. Homebrew installs both for you, and the installation guide covers every platform.

Then make a folder for your project and run protostar init inside it:

mkdir my-project
cd my-project
protostar init

Choose a template and the tools you want, look over a preview of every file it will create, and apply. When it's done, protostar guide shows how to run, test, and check the project. New to Python projects? Your First Project walks through every step.

Start From a Template

Each built-in template is a project shape. Pick one, then switch its tools on or off:

Every built-in template comes in two tiers. Workbench keeps the tooling light, for exploring and analysis. Production adds the full quality gate for something you'll publish: type checking, tests, commit hooks, CI, and releases. A project can move up whenever it's ready:

protostar sync --tier production

What It Can Set Up

The tooling matrix lists every tool, its flag, and the files it writes.

Everyday Commands

Make Your Own Template

A template is a short TOML file. This one gives every new service a team's tools, with stricter type checking than the default:

name = "Service"
description = "Our team's FastAPI service"

dependencies = ["fastapi", "uvicorn"]

ruff = true
mypy = true
pytest = true
ci = true

[dev.pyproject.strict_typing]
requires = "mypy"
content = '''
[tool.mypy]
strict = true
'''

Share it as a file, a URL, or a Git repository, and start projects from it:

protostar init --from https://github.com/your-org/service-template

Tag its releases, and every project made from it can move to the newest one with protostar sync --to latest. The authoring guide covers starter files, options, tiers, and checking a template in CI.

To see it all working, protostar-example-templates holds two templates, a one-file one and a fuller service, and protostar-example-project was made from one. When the template tagged a new release, a scheduled workflow in the project opened this update pull request on its own.

Go Deeper

Written for people who already know Python tooling:

How It's Built

Protostar edits other people's work, so it's built to be careful:

• It plans before it acts. Every change is worked out in memory and shown to you first. If a step fails or you press Ctrl+C, every file it wrote is restored exactly as it was.
• The engine is separate from the interface. The same core runs behind the interactive editor, the command line, and coding agents, which is why every command can also answer in JSON.
• It's tested thoroughly. Over 3,500 tests, including runs of the real tools, pass on Linux, macOS, and Windows, with strict type checking and at least 85% coverage.
• Its docs are checked against its code. Before every push, a script confirms that the commands, errors, exit codes, and file paths the docs mention still match the code.
• Performance stays visible. CI tracks help-command startup and the recipe editor's first frame, flagging large regressions; see the CI performance history.

Contributing

Bug reports and feature requests are welcome in GitHub issues. To work on Protostar itself, start with CONTRIBUTING.md and the developer guide.

Contact

License

This project is licensed under the MIT License. See the LICENSE file for details.