This is a quick guide to getting an existing Python project using, say, setuptools to using Poetry. This is mostly a reminder to myself. Refer to the official documentation for detail.
Firstly, have one or more versions of Python installed on your system. In my case, I have Python 3.9, 3.10, 3.11, 3.12, and 3.13 installed on macOS using Homebrew. Call these the “base” environments. We will be creating a venv for the development environment, and we need to distinguish the dev environment from the base.
In the base environment, install Poetry:
python3.x -m pip install poetry
Create an environment for the project, say it’s named “fooproj”:
python3.x -m venv ~/Venvs/fooproj
source ~/Venvs/fooproj/bin/activate
Go to your project directory, and generate a pyproject.toml file interactively. This will prompt you for dependencies for the package, and also for the development environment. You can skip it and add them later. Or, follow the prompts which will also ask if specific versions of packages are required.
cd Projects/fooproj ; poetry init
If you have an existing requirements.in file that is used with pip-compile:
for pkg in $( cat requirements.in ) ; do poetry add $pkg ; done
Create the poetry.lock file:
poetry lock
Build the package:
poetry build
Example run:
$ poetry build
Building fooproj (0.1.0)
Building sdist
- Building sdist
- Built fooproj-0.1.0.tar.gz
Building wheel
- Building wheel
- Built fooproj-0.1.0-py3-none-any.whl
Install the package to the dev environment as an editable package:
poetry sync
Example:
$ poetry sync
Installing dependencies from lock file
Package operations: 14 installs, 1 update, 0 removals
- Updating pip (25.0.1 -> 25.1.1)
- Installing packaging (25.0)
- Installing pyproject-hooks (1.2.0)
- Installing six (1.17.0)
- Installing babel (2.17.0)
- Installing build (1.2.2.post1)
- Installing click (8.1.8)
- Installing humanize (4.12.3)
- Installing python-dateutil (2.9.0.post0)
- Installing pytz (2025.2)
- Installing setuptools (80.3.1)
- Installing tzlocal (5.3.1)
- Installing wheel (0.45.1)
- Installing delorean (1.0.0)
- Installing pip-tools (7.4.1)
Installing the current project: fooproj (0.1.0)
$ pip show fooproj
Name: fooproj
Version: 0.1.0
Summary: foo bar
Home-page:
Author: Jane Hacker
Author-email: [email protected]
License: MIT
Location: /home/nobody/Venvs/poetry/lib/python3.13/site-packages
Editable project location: /home/nobody/Projects/fooproj
Requires: delorean
Required-by:
If requirements change, update the poetry.lock file, and sync to update the dev environment:
poetry lock ; poetry sync
Other notes:
- installing Poetry within the dev venv may result in weird things, like Poetry getting removed automatically; that’s why Poetry is installed in the base environment
- when using the Python Poetry Action in GitHub, you can have the workflow Poetry install into a virtualenv, and then run any commands using, say, “poetry run black --check fooproj”
