simple-modern-poetry

Python installation and setup is notoriously confusing for both beginners and experienced Python developers.

simple-modern-poetry is a minimal, modern Python project template for new projects (Python 3.10–3.13). This template should be a good base for serious work but also simple so it would work for any small project.

It is still surprisingly hard to find a good and 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 2.0 setup with dynamic versioning to make releases easier along with the shell and up plugins.

• Simple GitHub Actions CI workflow including 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

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 that in the future you can update your project to reflect any changes to this template by running copier update.

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
# Adjust code. 
# Remember to look for any unfilled _changeme_ strings and confirm the LICENSE file!
git add .
git commit -m "Initial commit from simple-modern-poetry."
# Create repo on GitHub.
git remote add origin git@github.com: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.

Alternatives

Poetry is likely the best package manager for most new projects. Those who love the very latest tools may want to consider uv instead of Poetry. Or for Conda dependencies, also consider the newer pixi package manager.

However, currently (early 2025) Poetry remains the most straightforward option, 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!