How to control package versions in your Python project

We all know the feeling of getting stuck in dependency and version hell when trying to run a new project. Or even our own team projects! For those of us struggling with this who use Python, there’s a neat solution called Poetry. This is a quick guide that I wish I read years ago, and I hope helps you now.

What is Poetry?

Poetry is a modern Python dependency management and packaging tool designed to simplify workflows and bring a more structured approach to our projects. It works just as well for solo use as it does for teams at scale. The key thing here is understanding that Poetry brings the power of version control to your Python workflow. Some of the benefits being as follows.

Dependency Resolution
Poetry excels at resolving complex dependency trees. It intelligently determines compatible versions for all your project’s requirements, minimizing conflicts.

Version Locking
Poetry creates a poetry.lock file to store the exact versions of all installed packages and their dependencies. This lock file guarantees reproducible environments across different systems or for future use.

Virtual Environments
Poetry seamlessly handles the creation and management of project-specific virtual environments.

Version Constraints:
Like requirements.txt, Poetry allows you to specify version constraints within your pyproject.toml file:

• ^1.2.3 (Caret): Compatible updates (1.2.3, 1.2.4, ... 1.9.9)

• ~=1.2.3 (Tilde): Minor updates (1.2.3, 1.2.4, ... 1.2.9)

• >1.2.0, <2.0.0 (Greater than/less than): More flexible ranges

Using Poetry

I’ve found that Poetry has been a quick tool to pick up and in actual use has made my workflow much more efficient.

1. Installation:

Intall Poetry with the pip command pip install poetry.

2. Project Initialization:

Use poetry init to initialize the instance and guide you through setting up your pyproject.toml.

3. Adding Dependencies:

Add the packages you want with poetry add package_name. This can also specify version constraints.

4. Installing Dependencies:

Install desired dependencies with poetry install. Note that Poetry respects the poetry.lock file or resolves versions if it's the first install. Nice one Poetry!

1. Updating Dependencies:

Use poetry update to update to latest compatible version.

Tutorials

There are some great tutorials on Youtube for learning how to get the most out of Poetry. Here’s the one I learned the most from.

Life is better with a little Poetry

Hopefully that helps you get up to speed on using Poetry with Python. Overall I’ve found that it helps me keep a cleaner project structure. This is made simple with the project configuration in the standard pyproject.toml file. I can also check there to see what the intention was in versions, so it's a good reference.

Another benefit has been the enhanced dependency resolver which is now preventing version conflicts proactively. No more oh-no moments for me or the team. This has also cleared up our separation of concerns, with Poetry focused on dependency management and packaging, I can now choose my preferred build tools. And overall, who can complain about a streamlined workflow, less things breaking, and the world of dependency management now a lot, lot, simpler.