How to control package versions in your Python project
Tags: python, poetry, programming, versioncontrol
Published: 2024-02-27 02:16:58

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!

5. **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.

{% embed https://www.youtube.com/watch?v=Ib7fNOIGM7E %}

## 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.