We’re happy to announce the new version of our Python project template: Substrate. The word “substrate” means “a substance or surface that an organism grows and lives on and is supported by” – by extension, the template is the “substrate” on which our Python projects live and by which they are supported.
What is Substrate? 🌱
Substrate is a new template for scaffolding Python packages and apps (which are different types of projects with different needs!) with the following design goals:
⏱️ Minimize the setup time of new Python projects
🧑💻 Make it easy to contribute to a project with one-click development environments
💅 Maximize code quality with linting checks & autofixes and static type analysis
✅ Follow industry best practices such as Conventional Commits, Semantic Versioning and Keep a Changelog
In short, we aim to help users of the template spend less time configuring & fixing ‘trivial’ things, like project structure, development environment, dependency management, collaborating with colleagues, ... in order to spend more time on valuable things, like applying their skills to the problem they’re trying to solve.
Substrate stands on the shoulders of giants 🏔️
Substrate was previously known as Poetry Cookiecutter (more on how we’ll continue to support Poetry Cookiecutter below!), which as the name implies was based on Poetry for dependency management and Cookiecutter & Cruft as the templating engine.
Since we created Poetry Cookiecutter in 2022, the Python ecosystem has evolved significantly. With the launch of Substrate, we integrate the latest and greatest of the recent innovations in a single Python project template:
Package and project management with uv
First, we switched to uv for package and project management, which comes with significantly better speed and DevEx:
In our experience, the switch to uv for package management results in a significant speedup when setting up your dev environment and running your CI builds. The full CI build & test suite for a fresh project runs on average in less than one minute, compared to almost 3 minutes with the previous version of the template!
Standards-compliant: uv fully supports PEP612, which means that you can configure your project metadata without needing tool-specific configuration files or sections.
uv supports specifying a resolution strategy, which the template uses to improve support for testing and publishing packages by introducing matrix builds with lowest-direct and highest resolution strategies in order to test a package across a large range of dependency versions.
uv has the ability to manage your Python interpreter as well. The project Dev Container is now based on the uv Docker image, which means you can switch Python versions on the fly in your development environment. This is especially useful when developing packages: you can test your package across different Python versions without having to rebuild your Dev Container.
Templating with Copier
Second, we switched to Copier for templating, which brings much improved DevEx for creating and upgrading scaffolding for your projects.
Copier’s when template configuration key allows us to reduce the amount of answers you need to provide when creating your projects, by not asking you for input when not needed.
Copier templates are versioned by default, so when you run copier update, your project scaffolding will always be updated based on a tagged release of Substrate, not just the HEAD of the main branch of Substrate. As a bonus, Substrate now maintains an official CHANGELOG.md.
Updating scaffolding doesn’t generate .rej files in the case of conflicts, like it did with cruft update in the past. Instead, you can review the scaffolding updates directly in your Git client, without having to manually review .rej files.
The Copier CLI is created using Typer, which results in a better-looking and more intuitive project scaffolding dialog.
We strongly simplified the Copier template by evaluating whether we could remove little-used or overly complex template features. This means less complex and more configurable scaffolding.
Try it out on your own projects—if you like it, give it a star on GitHub to support the project!
Continued support for Poetry Cookiecutter ❤️
We will continue to support the previous Cookiecutter-based template in the Substrate repository for backwards compatibility until the end of 2025.
If you were using the template for your projects before, you should be able to continue doing so. The Cookiecutter-based template will be purely in maintenance mode: new features will only be implemented in the new Copier template. In the meantime, we strongly encourage you to upgrade to the new template with our migration guide.
