Skip to main content

Managing Projects with Poetry

Modern Python Dependency Management

· 3 min read

In the previous unit, we used pip and requirements.txt to manage dependencies. Poetry takes this further with a more complete project management workflow.

Managing Projects with Poetry

What Poetry Does​

Poetry handles several things that pip and venv handle separately:

  • Creates and manages virtual environments automatically
  • Tracks dependencies with exact versions in a lock file
  • Distinguishes between production and development dependencies
  • Provides a standardized project structure

The trade-off is an additional tool to install and learn. For small scripts, pip is fine. For larger projects, Poetry's features become worthwhile.

Installing Poetry​

Install Poetry with:

curl -sSL https://install.python-poetry.org | python -

Verify the installation:

poetry --version

Creating a Project​

Start a new project with:

poetry new my_project

This creates a directory structure:

my_project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

The pyproject.toml file is the heart of a Poetry project.

Understanding pyproject.toml​

This file contains your project metadata and dependencies:

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = ""
authors = ["Your Name <email@example.com>"]

[tool.poetry.dependencies]
python = "^3.10"

[tool.poetry.dev-dependencies]
pytest = "^6.2"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

The [tool.poetry.dependencies] section lists packages your code needs to run. The [tool.poetry.dev-dependencies] section lists packages only needed during development, like testing frameworks.

Adding Dependencies​

Add a package with:

poetry add requests

This updates pyproject.toml and creates (or updates) a poetry.lock file. The lock file records the exact versions of every package and its dependencies, ensuring everyone gets identical environments.

For development-only packages:

poetry add pytest --dev

To install all dependencies from an existing project:

poetry install

Semantic Versioning​

When you add packages, Poetry uses semantic versioning constraints. The caret (^) in requests = "^2.25" means "compatible with 2.25".

Semantic versions follow MAJOR.MINOR.PATCH:

  • MAJOR: Breaking changes
  • MINOR: New features, backward compatible
  • PATCH: Bug fixes, backward compatible

The caret allows minor and patch updates but not major ones. So ^2.25 accepts 2.26 or 2.25.1, but not 3.0.

Running Your Code​

Poetry creates a virtual environment for your project. Run commands within it using:

poetry run python my_project/main.py

Or activate the environment in your shell:

poetry shell

Project: Convert to Poetry​

Let's convert the turtle-shapes project to use Poetry.

Navigate to your project and initialize Poetry:

cd path/to/turtle-shapes
poetry init

Answer the prompts for project name, version, and description. When asked about dependencies, add any packages your project uses.

Poetry creates a pyproject.toml. If you had a requirements.txt, you can remove it since pyproject.toml now tracks dependencies.

Install dependencies and create the lock file:

poetry install

Run your project through Poetry:

poetry run python main.py

Commit both pyproject.toml and poetry.lock to Git. These replace your old requirements.txt.

In the next unit, we'll shift back to Turtle graphics and explore game development concepts to prepare for building Snake in the final unit.