simple-modern-poetry

What is This?

simple-modern-poetry is a minimal, modern Python project template for new projects (Python 3.10–3.13) that uses Poetry 2.0. This template aims to be a good base for serious work but also simple so it's an easy option for any small project.

Note

See simple-modern-uv for a similar but template for uv, which is newer and may be best for new projects.

It is still surprisingly hard to learn modern best practices for setting up Python installations and tools without reading many pages of docs on pyenv, Poetry (and its 2.0 update), pipx, GitHub Actions etc.

So I'm sharing a template that I now use myself and that I can point friends to.

It aims to be "done right" with modern tools but still absolutely as simple as possible:

• Modern Poetry setup with dynamic versioning to make releases easier along with the shell and up plugins. (Why use Poetry? See below.)

• Simple GitHub Actions CI workflow including (optional) publishing to PyPI. To publish a release, just create a release on GitHub.

• Standard, modern linting, formatting, and testing with black, ruff, usort, mypy, codespell, and pytest.

• A starter readme with handy reminders on Python and Poetry setup/installation and basic dev workflows using to save time for you and users or collaborators.

• The whole template is only ~300 lines of code so you can read it and change what you want.

It doesn't have lots of options or try to use every bell and whistle. It just adds the above essential things that should be in place for any new Python project.

When to Use This Template

It should work whenever you want to use modern Python and Poetry and have a build workflow in GitHub. It does not handle:

• Using Docker (but you could add this later)

• Using Conda for dependencies (but note many deep learning libraries like PyTorch now support pip so this isn't as necessary as often as it used to be)

• Using a code repo or build system that isn't GitHub and GitHub Actions

(See below for other options.)

How to Use This Template

Note

By default this template uses MIT license. If you want a different license or are not publishing your project as open source, update license in pyproject.yaml and the LICENSE file. If desired, you may delete the .github/workflows/publish.yml file if you are not publishing to PyPI.

The template can be used in two ways. Option 1 is quickest. For more flexibility, consider Option 2.

Option 1: GitHub Template

Just use this template repository, which is the output of this template.

Go there and hit the "Use this template" button. Once you have the code, search for _changeme_ for all field names like project name, author, etc. You may also want to change the license/copyright.

Option 2: Use Copier

This template uses copier, which seems like the best tool nowadays for project templates. Using copier is the recommended approach since it then lets you instantiate the template variables, but it requires a few more commands.

Note that copier also has the cool feature to update your project template as this template improves in the future.

To create a new project repo with copier:

# Ensure you have Python 3.11+ and pipx installed. (If not, see below.)

# Install copier:
pipx install copier

# Clone this template:
copier copy gh:jlevy/simple-modern-poetry your-project-name
# Then follow the instructions.

You can enter names for the project, description, etc., or just press enter and later look for _changeme_ in the code.

Once you have the template set up, you will need to check the code into Git for Poetry to work. Create a new GitHub repo and add your initial code:

cd PROJECT
git init
# Make license or other initial adjustments if needed.
git add .
git commit -m "Initial commit from simple-modern-poetry."
# Create repo on GitHub.
git remote add origin [email protected]:OWNER/PROJECT.git  # or https://github.com/...
git branch -M main
git push -u origin main

Getting Started on Your Project

The default template readme covers the install and build workflows. It's just Poetry and a tiny Makefile with shortcuts. It also has concise documentation on installing Python and Poetry.

Updating Your Project Template

If you use Option 2 or if you pick Option 1 and correctly fill in your .copier-answers.yml file, you have the option to update your project with any future updates to this template at any time.

If this file is updated with your project name etc., then you can update your project to reflect any changes to this template by running copier update.

Alternatives

Poetry is one of the best package managers for modern Python projects. Those who love the latest tools may want to consider uv instead of Poetry.

Or for Conda dependencies, also consider the newer pixi package manager.

Currently (early 2025) Poetry is one of the most mature, straightforward options, especially since tool support, such as GitHub workflows and dependabot, still seem better for Poetry.

Assuming you want to use Poetry, there are several other good templates, such as cookiecutter-poetry and poetry-copier you may wish to consider.

This template takes a different philosophy. I found existing ones to be out of date or have lots of options and scaffolding for different frameworks. That's hard to maintain in the template repo and overwhelming to read at first. This is intended instead to be a very simple base. You can add to it if you want.

Contributing

PRs welcome on this repository (not on the GitHub template repo, which mirrors this one). Please use the Discussions tab with your feedback, questions, or suggestions!