Overlook PIP, Conda, and necessities.txt! Use Poetry As an alternative And Thank Me Later

Forget PIP, Conda, and requirements.txt! Use Poetry Instead And Thank Me Later
Picture by me with Midjourney


Library A requires Python 3.6. Library B depends on Library A however wants Python 3.9, and Library C is dependent upon Library B however requires the particular model of Library A that’s appropriate with Python 3.6.

Welcome to dependency hell!

Since native Python is garbage with out exterior packages for knowledge science, knowledge scientists can typically discover themselves trapped in catch-22 dependency conditions just like the one above.

Instruments like PIP, Conda, or the laughable necessities.txt recordsdata can’t resolve this downside. Really, dependency nightmares exist largely due to them. So, to finish their struggling, the Python open-source neighborhood developed the charming software referred to as Poetry.

Poetry is an all-in-one undertaking and dependency administration framework with over 25k stars on GitHub. This text will introduce Poetry and record the issues it solves for knowledge scientists.

Let’s get began.



Whereas Poetry could be put in as a library with PIP, it’s endorsed to put in it system-wide so you’ll be able to name poetry on the CLI anyplace you want. Right here is the command that runs the set up script for Unix-like programs, together with Windows WSL2:

curl -sSL https://set up.python-poetry.org | python3 -


If, for some bizarre purpose, you employ Home windows Powershell, right here is the appropriate command:

(Invoke-WebRequest -Uri https://set up.python-poetry.org -UseBasicParsing).Content material | py -


To verify if Poetry is put in accurately, you’ll be able to run:

$ poetry -v

Poetry (model 1.5.1)


Poetry additionally helps tab completion for a wide range of shells like Bash, Fish, Zsh, and so forth. Be taught extra about it here.



Since Poetry is an all-in-one software, you need to use it from the begin to the very finish of your undertaking.

When beginning a recent undertaking, you’ll be able to run poetry new project_name. It’ll create a default listing construction that’s nearly able to construct and publish to PyPI as a Python bundle:

$ poetry new binary_classification
Created bundle binary_classification in binary_classification

$ ls binary_classification
README.md  binary_classification  pyproject.toml  exams

$ tree binary_classification/

├── pyproject.toml
├── README.md
├── binary_classification
│   └── __init__.py
└── exams
    └── __init__.py


However we, knowledge scientists, not often create Python packages, so it’s endorsed to begin the undertaking your self and name poetry init inside:

$ mkdir binary_classification
$ poetry init


The CLI will ask you a collection of questions for setup, however you’ll be able to depart most of them clean as they are often up to date later:


Forget PIP, Conda, and requirements.txt! Use Poetry Instead And Thank Me Later
GIF. Mine.


The init command will produce essentially the most important file of Poetry – pyproject.toml. The file comprises some undertaking metadata, however most significantly, it lists the dependencies:

$ cat pyproject.toml
identify = "binary-classification"
model = "0.1.0"
description = "A binary classification undertaking with scikit-learn."
authors = ["Bex Tuychiev "]
readme = "README.md"
packages = [{include = "binary_classification"}]

python = "^3.9"

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


Proper now, the one dependency underneath software.poetry.dependencies is Python 3.9 (we’ll study what ^ is later). Let’s populate it with extra libraries.

If you wish to study what all of the fields in pyproject.toml file do, soar over here.


To put in dependencies on your undertaking, you’ll not have to make use of PIP or Conda, a minimum of straight. As an alternative, you’ll begin utilizing poetry add library_name instructions.

Right here is an instance:

$ poetry add scikit-learn@newest


Including the @newest flag installs the newest model of Sklearn from PyPI. It’s also potential so as to add a number of dependencies with none flags (constraints):

$ poetry add requests pandas numpy plotly seaborn


The great thing about add is that if the desired packages haven’t any model constraints, it’s going to discover the variations of all packages that resolve, i.e., not throw any errors when put in collectively. It’ll additionally verify in opposition to the dependencies already specified within the pyproject.toml.

$ cat pyproject.toml

python = "^3.9"
numpy = "^1.25.0"
scikit-learn = "^1.2.2"
requests = "^2.31.0"
pandas = "^2.0.2"
plotly = "^5.15.0"
seaborn = "^0.12.2"


Let’s attempt downgrading numpy to v1.24 and see what occurs:

$ poetry add numpy==1.24

As a result of seaborn (0.12.2) is dependent upon numpy (>=1.17,<1.24.0 || >1.24.0) ...
model fixing failed.


Poetry gained’t let it occur as a result of the downgraded model would battle with Seaborn. If this was PIP or conda, they’d gladly set up Numpy 1.24 and would grin again at us because the nightmare begins.

Along with commonplace installations, Poetry offers a flexible syntax for outlining model constraints. This syntax means that you can specify actual variations, set boundaries for model ranges (larger than, lower than, or in between), and pin down main, minor, or patch variations. The next tables, taken from the Poetry documentation (MIT License), function examples.

Caret necessities:


Forget PIP, Conda, and requirements.txt! Use Poetry Instead And Thank Me Later


Tilde necessities:


Forget PIP, Conda, and requirements.txt! Use Poetry Instead And Thank Me Later


Wildcard necessities:


Forget PIP, Conda, and requirements.txt! Use Poetry Instead And Thank Me Later


For much more superior constraint specs, go to this page of the Poetry docs.



One of many core options of Poetry is isolating the undertaking setting from the worldwide namespace in essentially the most environment friendly approach potential.

While you run the poetry add library command, here’s what occurs:

  1. When you initialized Poetry inside an current undertaking with a digital setting already activated, the library can be put in into that setting (it may be any setting supervisor like Conda, venv, and so forth.).
  2. When you created a clean undertaking with poetry new or initialized Poetry with init when no digital setting is activated, Poetry will create a brand new digital setting for you.

When case 2 occurs, the ensuing setting can be underneath /residence/consumer/.cache/pypoetry/virtualenvs/ folder. The Python executable can be there someplace as properly.

To see which Poetry-created env is energetic, you’ll be able to run poetry env record:

$ poetry env record


binary_classification-O3eWbxRl-py3.9 (Activated)


To change between Poetry-created environments, you’ll be able to run poetry env use command:

$ poetry env use other_env


You possibly can study extra about setting administration from here.



While you run the add command, Poetry will generate a poetry.lock file. Quite than specifying model constraints, like 1.2.*, it’s going to lock the precise variations of libraries you’re utilizing, like 1.2.11. All subsequent runs of poetry add or poetry replace will modify the lock file to replicate the adjustments.

Utilizing such lock recordsdata ensures that people who find themselves utilizing your undertaking can absolutely reproduce the setting on their machines.

Individuals have lengthy used options like necessities.txt however its format may be very free and error-prone. A typical human-created necessities.txt isn’t thorough as builders do not often hassle with itemizing the precise library variations they’re utilizing and simply state model ranges or worse, merely write the library identify.

Then, when others attempt to reproduce the setting with pip set up -r necessities.txt, PIP itself tries to resolve the model constraints, and that is the way you quietly find yourself in dependency hell.

When utilizing Poetry and lock recordsdata, none of that occurs. So, if you’re initializing Poetry in a undertaking with necessities.txt already current, you’ll be able to add the dependencies inside with:

$ poetry add `cat necessities.txt`


and delete the necessities.txt.

However, please word that some companies like Streamlit or Heroku nonetheless require previous necessities.txt recordsdata for deployment. When utilizing these, you’ll be able to export your poetry.lock file to a textual content format with:

$ poetry export --output necessities.txt



I need to depart the article with a step-by-step workflow to combine Poetry into any knowledge undertaking.

Step 0: Install Poetry on your system.

Step 1: Create a brand new undertaking with mkdir and name poetry init inside to initialize Poetry. If you wish to convert your undertaking right into a Python bundle later, create the undertaking with poetry new project_name.

Step 2: Set up and add dependencies with poetry add lib_name. It's also potential to manually edit pyproject.toml and add the dependencies underneath the [tool.poetry.dependencies] part. On this case, you need to run poetry install to resolve the model constraints and set up the libraries.

After this step, Poetry creates a digital setting for the undertaking and generates a poetry.lock file.

Step 3: Initialize Git and different instruments equivalent to DVC and begin monitoring the suitable recordsdata. Put pyproject.toml and poetry.lock recordsdata underneath Git.

Step 4: Develop your code and fashions. To run Python scripts, you should use poetry run python script.py in order that Poetry's digital setting is used.

Step 5: Take a look at your code and make any crucial changes. Iterate in your knowledge evaluation or machine studying algorithms, experiment with completely different methods, and refine your code as wanted.

Elective steps:

  1. To replace already-installed dependencies, use the poetry replace library command. replace solely works inside the constraints inside pyproject.toml so, verify the caveats here.
  2. In case you are ranging from a undertaking with necessities.txt, use poetry add cat necessities.txt to mechanically add and set up the dependencies.
  3. If you wish to export your poetry.lock file, you need to use poetry export --output necessities.txt.
  4. When you selected a bundle construction on your undertaking (poetry add), you'll be able to construct the bundle with poetry construct and it is going to be able to push to PyPI.
  5. Swap between digital environments with poetry env use other_env.

With these steps, you'll guarantee that you're by no means in dependency hell once more.

Thanks for studying!

Bex Tuychiev is a High 10 AI author on Medium and a Kaggle Grasp with over 15k followers. He loves writing detailed guides, tutorials, and notebooks on complicated knowledge science and machine studying subjects with a little bit of a sarcastic fashion.

Original. Reposted with permission.

Leave a Reply

Your email address will not be published. Required fields are marked *