Copyright 2017-2018 Jason Ross, All Rights Reserved

Star InactiveStar InactiveStar InactiveStar InactiveStar Inactive

What Is Poetry?

Poetry is a package and dependency manager for Python. It’s a replacement for the default manager, pip, It has a lot of advantages over pip, and it's definitely worth a look.

Why Would I Use It?

Python’s default package and dependency manager, pip, is quite a good system. It has evolved with the language, and lets you specify dependencies in text files; e.g.: requirements.txt, requirements-dev.txt etc. You can then install and update these packages in your virtual environments.

Alternatively you can do all of this with Poetry, as well as using it to:

  • - create new outline projects
  • - create and activate virtual environments
  • - build and package your projects into a wheel or sdist file
  • - publish your project to PyPI
  • - display your project’s dependency tree

To be honest, you can do all of this manually or with the tools that come with Python. But then, if all of these features are included in one tool, why wouldn’t you want to use that instead?

When Should I Use Poetry?

Poetry is a great system to use for any Python project. You can use it on existing projects as well as new projects, so if you’re using pip at the moment you can move to Poetry quite easily.

How Do I Get Started?

Follow the download and installation instructions at URL. Make sure you use the curl method to download and install it. Don’t use any of the other methods – I’ve never managed to get everything working when I’ve done that.

What Else Do I Need To Know?

There are some peculiarities with Poetry. Two that I’ve found are:

Version Pinning

If you’re using pip and one of your dependencies specifies a dependency of its own, without actually specifying a version, the latest version of this second level dependency will be downloaded. This might not be what you want.

You can prevent this from happening by specifying the second level dependency with a version in your own requirements.txt file. If you want to know a little more about this, there's more detail in Specify Your Dependency Versions.

Unfortunately, if you try this with Poetry it won’t work – it just downloads the latest version that fits all of the requirements, which is still the latest version of the second level dependency.

Unicode Error

On some versions of Ubuntu, with some versions of Python, and some versions of Poetry, you will get the following error:


‘latin-1’ codec can’t encode character ‘\u2022’ in position 2: ordinal not in range(256)

at ~/.poetry/lib/poetry/_vendor/py3.6/clikit/io/output_stream/ in write

This is caused by a localization error and can be fixed, at least until you upgrade Ubuntu, Python and/or Poetry, by calling Poetry as follows:

LC_ALL=C.UTF-8 ~/.poetry/bin/poetry

In short, this forces the system to use byte compatibility and byte-ordered sorting. It’s rather more complex than just that, but trust me, it works.

Who Uses It?

Once you’ve been using Python for a while, you’ll start to notice there are places where pip, and the other Python utilities, have a few “gaps” that Poetry fills very well. You’re not the first – lots of other Python developers have found this. Give it a try – it really will make things much easier!