Home » Virtual Environments And Package Management » Python Poetry: Package and venv Management Made Easy
An open book showing pyproject.toml with a padlock for the lock file, beside a quill in an inkwell

Python Poetry: Package and venv Management Made Easy

By Published Updated

Poetry is a package manager for Python. It’s a tool that serves multiple purposes. It:

  • Conveniently manages your virtual environments (no need to create them manually)
  • Is a great tool for installing Python packages (you don’t need pip install anymore)
  • Helps you to manage your dependencies
  • Can be used for building Python packages that you can share with the world

This article takes a close look at Python Poetry. We’ll first install it properly, and then I’ll show you how to create projects with Poetry and manage your virtual environment and project dependencies. Everything on this page is based on Poetry 2.x, which changed quite a few commands compared to Poetry 1.x. If you followed an older tutorial and a command doesn’t work, that’s probably why.

Why Poetry?

Poetry has several advantages over using pip directly. For starters, it’s an intuitive tool for installing Python packages in a virtual environment. In addition, it conveniently manages your virtual environments as well. Poetry also manages your dependencies: it will try to find a combination of dependencies that work together nicely and store this combination in a so-called lock file.

Once you get to a point where you want to distribute your software as a Python package, Poetry greatly simplifies the building and uploading of Python packages as well!

Installing Python Poetry

Poetry should live in its own isolated environment, so it won’t clash with the packages of your projects or of your system Python. There are a few good ways to get that.

Using the installer

Poetry has an official installer script that sets up Poetry in its own virtual environment. On Windows, run this in PowerShell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -Code language: PowerShell (powershell)

And on a Mac or Linux system:

curl -sSL https://install.python-poetry.org | python3 -Code language: PowerShell (powershell)

The installer tells you where it put the poetry command. If your shell can’t find it afterward, add that directory to your PATH.

Using pipx or uv

If you already use pipx or uv, you can let them install Poetry as an isolated tool. Pick one:

pipx install poetry

# Or with uv:
uv tool install poetryCode language: PowerShell (powershell)

I don’t recommend a plain pip install poetry or pip install --user poetry. On many Linux distributions and on Homebrew’s Python, pip refuses to install into the system Python (you’ll get an “externally-managed-environment” error). Even where it works, Poetry’s own dependencies end up mixed with everything else you installed.

Test if your poetry installation works

Finally, test if the installation worked with the following command:

poetry --versionCode language: PowerShell (powershell)

If you see something like Poetry (version 2.5.1), the installation was successful.

Keeping Python Poetry up-to-date

If you used the Poetry installer script, you can use the following command to update Poetry:

poetry self updateCode language: PowerShell (powershell)

If you installed it with pipx or uv, update it with that same tool:

pipx upgrade poetry

# Or with uv:
uv tool upgrade poetryCode language: PowerShell (powershell)

Starting a project with Python Poetry

When you start a project with Poetry, quite a few things will happen. Let’s begin by creating a new project:

poetry new demoCode language: PowerShell (powershell)

This command created a new directory called demo in the current directory. When we inspect the directory, we’ll see a few files:

demo ├── pyproject.toml ├── README.md ├── src │ └── demo │ └── __init__.py └── tests └── __init__.py