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.
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.
Install Protostar with uv on any platform:
uv tool install protostarOr with Homebrew on macOS:
brew install jacksonfergusondev/tap/protostarProtostar 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 initChoose 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.
Each built-in template is a project shape. Pick one, then switch its tools on or off:
| Template | For |
|---|---|
cli |
A command-line app, with Typer and Rich |
api |
A web API, with FastAPI |
lib |
A library other people install from PyPI |
ml |
Machine learning and data science, with PyTorch and Jupyter |
astro |
Astronomy and astrophysics data analysis, with Astropy |
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| Area | Tools |
|---|---|
| Code quality | Ruff, plus a type checker: mypy, ty, or Pyrefly |
| Tests | pytest, with coverage reports on Codecov |
| Commit checks | pre-commit or prek hooks, and Commitizen for commit messages |
| Automation | GitHub Actions CI, releases to PyPI, and Renovate for dependency updates |
| Documentation | Zensical sites, and publishing on Read the Docs |
| Everyday work | just for short commands, direnv for environments, and Docker images |
| Collaboration | An AGENTS.md for coding assistants, and contributing guides and issue forms |
| Markdown | rumdl or markdownlint |
The tooling matrix lists every tool, its flag, and the files it writes.
| Command | What it does |
|---|---|
protostar init |
Set up a new project, or bring Protostar into one you already have |
protostar status |
Show what an update would change, and anything waiting for your decision |
protostar sync |
Apply updates from your template and from Protostar, keeping your edits |
protostar guide |
Show how to run, test, check, and document this project |
protostar eject |
Stop tracking the project, and keep every file |
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-templateTag 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.
Written for people who already know Python tooling:
| If you want to | Read |
|---|---|
Compare Protostar with Copier, Cookiecutter, and uv init |
Why Protostar? |
| Review and settle updates in a project | Project Lifecycle |
| Open update pull requests and check projects in CI | Automating Updates |
| Drive Protostar from scripts or coding agents | Agent & Machine Interface |
| Write and publish templates for a team | Authoring Templates |
| Look up every command and flag | CLI Reference |
| See how planning, merging, and rollback work | Design Principles |
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.
Bug reports and feature requests are welcome in GitHub issues. To work on Protostar itself, start with CONTRIBUTING.md and the developer guide.
This project is licensed under the MIT License. See the LICENSE file for details.