Managing Python Deps with Poetry

Introduction Managing dependencies in Python projects can often become cumbersome, especially as projects grow in complexity. Poetry is a modern dependency management and packaging tool that simplifies this process, offering a streamlined way to create, manage, and distribute Python projects. Use Cases Poetry offers several advantages over traditional dependency managers like pip and venv: 1) Simplified Dependency Management: Unlike requirements.txt, Poetry uses a pyproject.toml file to handle dependencies more effectively. 2) Automatic Virtual Environments: Poetry automatically creates and manages virtual environments for your projects. 3) Semantic Versioning: It ensures that dependencies adhere to semantic versioning, reducing compatibility issues. 4) Publishing Made Easy: With a single command, you can publish your package to PyPI. Although there are a lot of use cases, in this article we will focus on how to setup a project with poetry and manage its dependencies. Installation The easiest way to do this is to use pipx as it installs packages in an isolated environment. If you don't have poetry install you can insatll it from here. pipx install poetry There are other methods of installation listed here. Project Setup There are a few ways to setup your project with poetry. In the official poetry documentation it is recommended to use poetry new . This creates a folder with the name of the project and creates some boilerplate which include a README.md, src, tests and pyproject.toml. I, however, prefer using poetry init to initialize poetry in a project. This allows me to manually configure the directory structure. You can find the code used in this article at my github repository 1) Create project directory: mkdir poetry-test && cd poetry-test 2) Initialize Poetry: This will run an interactive module in which you can enter values according to your needs. After running it will only create a pyproject.toml. poetry init 3) Setup Directory Structure: For this article we will make a simple fastapi endpoint so I will follow the general dir structure of a fastapi application along with a README.md. 4) Installing dependencies: We only have one dependency as of now - "fastapi[standard]". poetry add "fastapi[standard]" You can mention a particular version as well. Running this will update the pyproject.toml and create a poetry.lock file. 5) Fastapi endpoint code: Add this code in the app/main.py file. from fastapi import FastAPI app = FastAPI() @app.get("/") async def root(): return {"message": "Hello World"} Now to run this server run poetry run fastapi dev app/main.py and then go to http://localhost:8000/. And that's it. The server is up. Poetry commands Now let's take a look at the poetry commands we used (and some more) to understand what exactly they do. 1) poetry init - Initialize a poetry project interactively. 2) poetry add - Add a dependency to the environment. 3) poetry add --dev - Add a dev dependency to the environment. 4) poetry install - If you have a pyproject.toml file you can run this to install the dependencies. Similar to pip install -r requirements.txt 5) poetry run - This allows us to run a command in the poetry environment without actually entering the environment. 6) poetry shell - This allows you to enter the poetry environment. Similar to sourcing the virtual environment. In newer poetry versions the shell command does not come built-in but needs to be installed as a plugin. This can be done with the following command - pipx inject poetry poetry-plugin-shell 7) poetry show - Lists the installed dependencies. Similar to pip freeze or pip list 8) poetry show --tree - Lists the installed dependencies in tree form(recommended). And, that's it from my side. Check out the docs of poetry at https://python-poetry.org/docs/ for other info. Byee.

Feb 27, 2025 - 09:01

Introduction

Managing dependencies in Python projects can often become cumbersome, especially as projects grow in complexity. Poetry is a modern dependency management and packaging tool that simplifies this process, offering a streamlined way to create, manage, and distribute Python projects.

Use Cases

Poetry offers several advantages over traditional dependency managers like pip and venv:

1) Simplified Dependency Management: Unlike requirements.txt, Poetry uses a pyproject.toml file to handle dependencies more effectively.

2) Automatic Virtual Environments: Poetry automatically creates and manages virtual environments for your projects.

3) Semantic Versioning: It ensures that dependencies adhere to semantic versioning, reducing compatibility issues.

4) Publishing Made Easy: With a single command, you can publish your package to PyPI.

Although there are a lot of use cases, in this article we will focus on how to setup a project with poetry and manage its dependencies.

Installation

The easiest way to do this is to use pipx as it installs packages in an isolated environment.

If you don't have poetry install you can insatll it from here.

pipx install poetry

There are other methods of installation listed here.

Project Setup

There are a few ways to setup your project with poetry.

In the official poetry documentation it is recommended to use poetry new . This creates a folder with the name of the project and creates some boilerplate which include a README.md, src, tests and pyproject.toml.

I, however, prefer using poetry init to initialize poetry in a project. This allows me to manually configure the directory structure.

You can find the code used in this article at my github repository

1) Create project directory:

mkdir poetry-test && cd poetry-test

2) Initialize Poetry:

This will run an interactive module in which you can enter values according to your needs.
After running it will only create a pyproject.toml.

poetry init

3) Setup Directory Structure:

For this article we will make a simple fastapi endpoint so I will follow the general dir structure of a fastapi application along with a README.md.

4) Installing dependencies:

We only have one dependency as of now - "fastapi[standard]".

poetry add "fastapi[standard]"

You can mention a particular version as well. Running this will update the pyproject.toml and create a poetry.lock file.

5) Fastapi endpoint code:

Add this code in the app/main.py file.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

Now to run this server run

poetry run fastapi dev app/main.py

and then go to http://localhost:8000/.

And that's it. The server is up.

Poetry commands

Now let's take a look at the poetry commands we used (and some more) to understand what exactly they do.

1) poetry init - Initialize a poetry project interactively.

2) poetry add - Add a dependency to the environment.

3) poetry add --dev - Add a dev dependency to the environment.

4) poetry install - If you have a pyproject.toml file you can run this to install the dependencies.

Similar to pip install -r requirements.txt

5) poetry run - This allows us to run a command in the poetry environment without actually entering the environment.

6) poetry shell - This allows you to enter the poetry environment.

Similar to sourcing the virtual environment.

In newer poetry versions the shell command does not come built-in but needs to be installed as a plugin.
This can be done with the following command -

pipx inject poetry poetry-plugin-shell

7) poetry show - Lists the installed dependencies.

Similar to pip freeze or pip list

8) poetry show --tree - Lists the installed dependencies in tree form(recommended).

And, that's it from my side. Check out the docs of poetry at https://python-poetry.org/docs/ for other info.
Byee.