Beginner Guide on “Poetry”, New Python dependency management tool

yukinagae profile image Yuki Nagae ・3 min read

Why I write this post?

Once I wrote a blog post about “pipenv”, which is one of the Python package management tools, Dylan gave me a comment on the post.

He pointed out some of the issues on pipenv, and his suggestion was to use Poetry instead of pipenv.

In this post, I’ll briefly cover what Poetry is and some usage of it. This is just a first try to use Poetry, and hopefully, I write more details in the future blog posts :)

What is “Poetry” and why?

Poetry is a Python dependency management tool.

The main reason why Poetry developed is mentioned here.

Packaging systems and dependency management in Python are rather convoluted and hard to understand for newcomers. Even for seasoned developers it might be cumbersome at times to create all files needed in a Python project:setup.py, requirements.txt, setup.cfg, MANIFEST.in and the newly added Pipfile.

This is really true that there are many files we should consider such as:

  • setup.py
  • requirements.txt
  • setup.cfg
  • Pipfile and Pipfile.lock (pipenv)

To solve this messy situation, Poetry comes here for us with only one pyproject.toml file to manage all the dependencies.

Now, let’s setup Poetry!

Setup Poetry


  • Python 2.7 or 3.4+

I’ll use Python 3.6.0 in this post.

$ python --version
Python 3.6.0


Install Poetry via an installer provided.

$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
Retrieving Poetry metadata

# Welcome to Poetry!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:


This path will then be added to your `PATH` environment variable by
modifying the profile files located at:


You can uninstall at any time with `poetry self:uninstall`,
or by executing this script with the --uninstall option,
and these changes will be reverted.

Installing version: 0.12.12
  - Downloading poetry-0.12.12-darwin.tar.gz (7.23MB)

Poetry (0.12.12) is installed now. Great!

To get started you need Poetry's bin directory ($HOME/.poetry/bin) in your `PATH`
environment variable. Next time you log in this will be done

To configure your current shell run `source $HOME/.poetry/env`

To activate poetry command, run the following command:

source $HOME/.poetry/env

Now, poetry command should be available. Let’s check the Poetry version installed.

$ poetry —version
Poetry 0.12.12

It works!

Poetry demo

Create a template

First, I’ll create a demo app.

poetry new poetry-demo

The project structure is like this.

$ cd poetry-demo
$ tree
├── README.rst
├── poetry_demo
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_poetry_demo.py

Let’s see pyproject.toml.

name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["[Your Name] <[Your Email]>"]

python = "^3.6"

pytest = "^3.0"

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

Add dependency

I can specify a dependency in the pyproject.toml file directly, but it looks easy for me to use add command.

poetry add pendulum

Automatically, pendulum is added to the pyproject.toml file.

python = "^3.6"
pendulum = "^2.0"

Also, poetry.lock is created.

$ tree
├── README.rst
├── poetry.lock
├── poetry_demo
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_poetry_demo.py

Since this is just a first try to use Poetry, I’ll continue using it and may write a blog post again if I find something useful :)


There are several things I’d like to try:

  • [ ] How to integrate with existing requirements.txt?
  • [ ] Try Poetry publish command to publish my package to PyPI
  • [ ] Compare Poetry with pipenv



Editor guide
mcepl profile image
Matěj Cepl

This is so beautiful example of xkcd.com/927/ !

jweberdj profile image
Joshua Weber

Poetry is great! Does anyone know how to run a python script with poetry and use a python option?

Ideally, need to invoke a python script as so: python3 -u script.py

andrewspittlemeister profile image
Andrew Spittlemeister

You can use poetry run <your commands here> to run anything within the virtual environment described by the pyproject.toml file. So poetry run python3 -u script.py.

helpermethod profile image
Oliver Weiler

I'm baffled that dependency management is still an unsolved problem in the Python community :/.

khalyomede profile image

So true... It is not like they do not have any inspiration (npm, composer, ...).

Also, they really should get rid of that environement in favor of local files. I wonder if poetry make a virtual environnement or not.

yukinagae profile image
Yuki Nagae Author

Poetry uses or creates a virtual environment according to the below doc. Maybe we cannot escape from virtual environments when we use Python...

Poetry will check if it's currently inside a virtualenv and, if not, will use an existing one or create a brand new one for you to always work isolated from your global Python installation.

see: poetry.eustace.io/docs/basic-usage...

paolodina profile image
Paolo Dina

Well, about requirements.txt here it is github.com/python-poetry/poetry/is...