moving from pipenv to poetry

In the past 1-1.5 years I’ve used pipenv, which worked very well for me but it was annoyingly slow. Creating a virtual environment took a minute sometimes, and installing the dependencies often took several minutes. I’ve heard lots of good things about poetry, so I decided to give it a try. After reading its documentation, I could do everything with it that I needed, so in the future I’ll use poetry for managing my virtual environments.

Getting started
The home page of poetry is here.

The installation is a bit speacial: https://poetry.eustace.io/docs/. After the installation, open a new terminal and issue the command “poetry“. If it starts, then the installation was successful :)

The installer puts poetry in the folder ~/.poetry .

By default, new virtual environments are put in the folder ~/.cache/pypoetry/virtualenvs/. However, I prefer collecting the virtual environments in ~/.virtualenvs. For this, issue the following command:

$ poetry config settings.virtualenvs.path $HOME/.virtualenvs

Actually, it’s a good idea to put this value in an environment variable too. Add this line to the end of your ~/.bashrc file:

export WORKON_HOME=$HOME/.virtualenvs

The config info is stored in the file ~/.config/pypoetry/config.toml .

Update poetry

poetry self:update

Use case #1: Create a new poetry project from scratch

$ mkdir demo
$ cd demo
$ poetry new [--src] .

It will create the basic structure of a new project (scaffolding). If you want to store the source files in the directory “src/“, then add the option “--src“. The dot at the end means the current directory.

Create / activate / deactivate the virtual environment

poetry shell

If the virt. env. doesn’t exist yet, poetry will create it. For this to work, you need to have the file pyproject.toml .
If the virt. env. exists, then “poetry shell” will activate it. Actually, it opens a subshell.
To deactivate the virt. env., simply close the subshell (with Ctrl-D for instance).

Install / remove a package

poetry add requests [--dev]

It’ll install the given dependency (requests in the example) and add it to your pyproject.toml file. With the option “--dev“, the package will be installed as a development dependency.

poetry remove requests

Remove the package and if it installed some sub-dependencies, then those packages are also removed.

Help
Simply launch “poetry” to see all the options. To get help about an option, e.g. about “install”, then use this:

poetry help install

Show installed packages

$ poetry show [--no-dev]
$ poetry show --tree [--no-dev]

Show the list of installed packages. With “--tree“, show the result in a tree layout. With “--no-dev“, development packages will be hidden.

Version control
Upload both pyproject.toml and poetry.lock in your version control system.

Where is the directory of the virtual environment?
To figure out the directory of the virt. env., use the command

poetry show -v

and the result will be in the first line. If you need just this information, then here is how to extract it:

venv_folder=`(poetry show -v | head -1) 2>/dev/null | cut -d" " -f3`

Which packages are outdated?

$ poetry show -o
$ poetry show --outdated    # same thing

It will show which packages have newer versions.

Update a package / all packages

$ poetry update requests

Update the given package. However, it takes into account the SemVer rules, defined in pyproject.toml . Read more about versioning here: https://poetry.eustace.io/docs/versions/.

poetry update

Update all packages. Again, it follows the SemVer rules.

Edit your pyproject.toml
If you edit the .toml file, you can verify it with

poetry check

Use case #2: Convert an existing project to a poetry project
All right. Say you have a project and you want to convert it to a poetry project. For example it was managed by pipenv but you want to switch to poetry. Here are the steps:

• enter the project directory
• “poetry init -n” will create a pyproject.toml file without asking any embarrassing questions. Review this file if you want. For instance, set the proper Python version.
• “poetry shell” — create a virt. env. for the project
• “poetry add pkg1 pkg2” — install the given packages (copy them from your Pipfile, for instance)
• “poetry add pkg1 pkg2 --dev” — install the development packages

Use case #3: Checkout a poetry project
Let’s say you download a project from GitHub and it uses poetry, i.e. it has a pyproject.toml file and possibly a poetry.lock file too. How to create a virt. env. for it? How to install its packages? Aaaargghhhh!

Relax and issue this simple command inside the project folder:

poetry install [--no-dev]

By default, it also installs the development packages. Use “--no-dev” if you don’t need the dev. packages.

Windows support
Poetry works under Windows too. The installation is the same. I had to install curl for Windows, but then I could download the installer without any problem.

The installer adds the folder %USERPROFILE%\.poetry\bin to your PATH.

The virtual environments are created here: %USERPROFILE%\AppData\Local\pypoetry\Cache\virtualenvs\ .

Unfortunately, when I activated a virt. env., the prompt didn’t change.

Troubleshooting

Under Ubuntu 18.04 I had to use some tricks to force poetry to use Python 3. Find the details here. In short: edit the file ~/.poetry/bin/poetry and update its first line to #!/usr/bin/env python3. If you update poetry, it’s very likely you’ll have to change this file again.

Links

• How to Rock Python Packaging with Poetry and Briefcase