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 runfor everything — usepoetry shellfor interactive work. - Mixing pip and poetry — don’t
pip installin a Poetry project. Usepoetry add. - Wrong Python version — Poetry uses the system Python. Use
pyenvto 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 dependenciespoetry.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.