Tech With Galvan
Back to Articles
TechApr 25, 2027 • 5 min read

Python Poetry: Dependency Management and Packaging

Poetry for Python — dependency management, lockfiles, virtual environments, and publishing. Complete guide with real examples.

Galvan
Galvan

Founder & Creator

Introduction

Poetry is Python’s most popular dependency manager and packaging tool — it handles dependencies, lockfiles, virtual environments, and publishing in one tool. While uv is the new hotness, Poetry is still widely used and has a mature ecosystem.

This post covers Poetry from setup to publishing.

Setup

# Install (recommended: via official installer)
curl -sSL https://install.python-poetry.org | python3 -

# Or via pipx
pipx install poetry

# Verify
poetry --version

Step 1: Create a project

poetry new my-project
cd my-project

Creates:

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

Or initialize in an existing directory:

cd existing-project
poetry init   # interactive

Step 2: Add dependencies

poetry add requests pandas
poetry add --group dev pytest ruff mypy
poetry add --group docs sphinx

Updates pyproject.toml and creates poetry.lock (reproducible lockfile).

Step 3: Install

poetry install              # install all deps (including dev)
poetry install --without dev  # production only
poetry install --with docs    # include docs group

Creates a virtual environment automatically (in .venv or Poetry’s cache).

Step 4: Run code

poetry run python main.py
poetry run pytest
poetry run streamlit run app.py
poetry shell   # activate the venv (like source .venv/bin/activate)

Step 5: Lock file

poetry lock          # regenerate lockfile
poetry lock --no-update  # update lock without changing versions

Commit poetry.lock to git for reproducible builds.

Step 6: Update dependencies

poetry update           # update all
poetry update requests  # update specific
poetry show --outdated  # show outdated packages

Step 7: Build and publish

poetry build            # creates dist/ (sdist + wheel)
poetry publish          # upload to PyPI
poetry publish --repository testpypi  # test first

Poetry handles building and publishing in one tool.

pyproject.toml structure

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A short description"
authors = ["Your Name <[email protected]>"]
readme = "README.md"
license = "MIT"
packages = [{include = "my_project"}]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.31.0"
pandas = "^2.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
ruff = "^0.1.0"

[tool.poetry.scripts]
my-cli = "my_project.cli:main"

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

Version constraints

Constraint Meaning Example
^ (caret) >= current, < next major ^2.3.0 → >=2.3.0, <3.0.0
~ (tilde) >= current, < next minor ~2.3.0 → >=2.3.0, <2.4.0
* Any version *
>= Greater or equal >=2.0.0
Exact Exact version ==2.3.0

Caret (^) is the default and recommended for most deps.

Poetry vs uv vs pip

Poetry uv pip + venv
Speed Medium Very fast (10-100x) Slow
Lockfile Yes (poetry.lock) Yes (uv.lock) No (pip freeze)
Venv management Yes (auto) Yes (auto) Manual
Python versions No (use pyenv) Yes (built-in) No
Publishing Yes (built-in) Yes (built-in) Manual (twine)
Ecosystem Mature Growing fast Universal
Learning curve Medium Low Low

In 2026: uv is faster and simpler. Poetry is more mature with a larger ecosystem. For new projects, uv is recommended. For existing Poetry projects, stay unless you need the speed.

Common workflows

New project

poetry new my-app
cd my-app
poetry add streamlit pandas
poetry add --group dev pytest ruff
poetry run streamlit run app.py

Existing project

cd existing-project
poetry init
poetry add -r requirements.txt
poetry install

CI/CD

# GitHub Actions
- uses: snok/install-poetry@v1
- run: poetry install
- run: poetry run pytest

Common mistakes

  • Not committing poetry.lock — breaks reproducibility. Always commit it.
  • Using poetry run for everything — use poetry shell for interactive work.
  • Mixing pip and poetry — don’t pip install in a Poetry project. Use poetry add.
  • Wrong Python version — Poetry uses the system Python. Use pyenv to switch versions, or migrate to uv.
  • Forgetting --group dev — dev deps (pytest, ruff) should be in a dev group, not main deps.

Key Concepts

  • Poetry = dependency manager + packager + publisher
  • pyproject.toml = project metadata and dependencies
  • poetry.lock = reproducible lockfile
  • Groups = dependency groups (dev, docs, test)
  • Caret (^) = version constraint (>= current, < next major)
  • poetry run = run in the project’s venv

What to Try Next

  • Migrate to uv for 10x faster builds.
  • Publish your package to PyPI.
  • Add pytest with Poetry’s dev group.
  • Combine with type hints for type-safe deps.

FAQ

Poetry vs uv — which to choose in 2026?

uv is faster, simpler, and handles Python versions. Poetry has a more mature ecosystem and more features (plugins, custom scripts). For new projects, uv. For existing Poetry projects, stay unless you need the speed.

Poetry vs pipenv?

pipenv is largely unmaintained. Poetry is the better choice — faster, better lockfile, more features. If you’re on pipenv, migrate to Poetry or uv.

Can Poetry handle monorepos?

Yes — Poetry supports workspace/monorepo setups with multiple pyproject.toml files. But it’s complex. For monorepos, consider uv (better monorepo support) or pants/nx.