Poetry is modestly described by its official documentation as a dependency management tool, but it is in fact emerging as a de facto standard†) to
[†]: Quoting How to manage Python projects with Poetry
control virtual environments
create and publish packages/libraries
quickly set up new Python projects (or to easily convert existing ones)
Even though the Python eco-system is rich with internal (venv, pyvenv) and external tools (pip, pyenv, pipenv, virtualenv, etc.) that take on one or two of the roles listed above, this diversity can become an issue:
differing conventions and proliferating command line options incur some cognitive overhead
one has to carefully choose which tools to use together
not all such projects run on every operating system (e.g., pyenv does not support Windows directly)
Poetry aims to consolidate the functionality of all these tools (TODO: paraphrase, https://www.software.com/src/poetry-can-redefine-the-future-of-python), while striving to stay easy to use and configure.
[†]: Paraphrasing Is Poetry the future of Python?
Nix is a cross-platform system package manager supported on most major distributions of Unix derivative operating systems (Linux, BSDs, MacOS, etc.) but it is not available on Windows.
The title of the section is deliberately not called "Installation" also because the "Installation" section of the Poetry documentation comprehensively covers this topic for operating systems not managed with Nix (the reason I elected to demonstrate using Poetry with Nix in the first place), and because Nix allows using software (and software components) in a way that doesn't conform to the traditional use of the term "installation".
nix-shell$ nix-shell -p python3 poetry
nix-shell will start a sub-shell with the latest Python 3 and Poetry executables, and one can start hacking.
NOTE: Once exiting the sub-shell,
python3andpoetryare still available on the system (seewhich poetryandwhich python3) but they are not referenced in thePATHenvironment variable. Hence they will need to be aliased or called by their full path. (Packages used withnix-shellare also subject to garbage collection after leaving the sub-shell.)
nix-shell can also be used to set up a more elaborate development environment, and this is probably the most flexible and convenient way.
ASIDE: The blog post Developing Python with Poetry &
poetry2nix: reproducible flexible Python environments nicely expands on this topic.
nix-env$ nix-env -i python3 poetry
The only difference between with this one-liner and the one in the previous section is that python3 and poetry are now available in PATH, and they won't be garbage collected (unless removed with [nix-env -e] first).
TODO:
nix-env -i poetryfails witherror: selector 'poetry' matches no derivations; related to channels?
WARNING: This is a more advanced (and sprawling) Nix topic, and I still believe that the most convenient way is using
nix-shell, but it's mentioned here for completeness sake.
The following are the best places to start with, depending
whether on NixOS: Chapter 6. Package Management in the NixOS manual
or using Nix on other Unix derivatives: 2.6. Declarative Package Management of the Nixpkgs manual
Nix also offers a lot of freedom on how to do things, and this can complicate things, therefore the following resources are also suggested for reading:
Declarative Configuration on the NixOS Wiki
Declarative package management for normal users thread on NixOS Discourse
Declarative approach to installing packages for user only on Reddit
How do I do declarative package management using nix package manager on Debian? on Reddit
Difference between nix profiles and home-manager on NixOS Discourse
/etc/nixos/configuration.nix vs ~/.config/nixpkgs/config.nix on Reddit
There are many "getting started" guides out there (e.g., 1, 2, 3, 4, 5, 6), therefore I was striving to show (a hint of) the big picture.
WARNING: Please take any info in this section with grain of salt: put this together based on the official documentation, but I'm a new to Python, and it hasn't been reviewed by more experienced users at all.
The flowchart below shows how Poetry's configuration options come into play when
taking out your project for a spin (using commands such as poetry shell, poetry run)
making changes in configuration (e.g., with poetry config), or most times
managing the virtual environment (mostly when using poetry env).
The above flowchart may not convey clearly how Poetry chooses the virtual environment to use so this table is to provide an alternative representation:
virtualenvs.create |
virtualenvs.in-project |
{project-root}/.venv present |
expected behavior |
|---|---|---|---|
true (default) |
true |
yes | use {project_root}/.venv |
| no | create {project_root}/.venv |
||
false |
yes | ignore {project_root}/.venv and use/create global one at virtualenvs.path |
|
| no | use/create global one at virtualenvs.path |
||
| other (∉ { true, false}) |
yes | use {project_root}/.venv |
|
| no | (?) use/create global one at virtualenvs.path |
||
false(and pip is available) |
true |
yes | I presume that as virtual environments are disabled, the rest depends on the active Python version and pip. |
| no | |||
false |
yes | ||
| no | |||
| other (∉ { true, false}) |
yes | ||
| no | |||
| other (∉ { true, false}) |
true |
yes | Given that the default value of virtualenvs.in-project boolean configuration option is None, this I presume that virtualenvs.create may also be given a value other than true or false - although unsure what [Poetry]'s behaviour will be. |
| no | |||
false |
yes | ||
| no | |||
| other (∉ { true, false}) |
yes | ||
| no |