Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
For the basic usage introduction we will be installing
pendulum, a datetime library.
First, let's create our new project, let's call it
$ poetry new poetry-demo
This will create the
poetry-demo directory with the following content:
poetry-demo ├── pyproject.toml ├── README.rst ├── poetry_demo │ └── __init__.py └── tests ├── __init__.py └── test_poetry_demo.py
pyproject.toml file is what is the most important here. This will orchestrate
your project and its dependencies. For now, it looks like this:
[tool.poetry] name = "poetry-demo" version = "0.1.0" description = "" authors = ["Sébastien Eustace <email@example.com>"] [tool.poetry.dependencies] python = "*" [tool.poetry.dev-dependencies] pytest = "^3.4"
If you want to add dependencies to your project, you can specify them in the
tool.poetry.dependencies section. You can use
vim to edit files in the terminal.
[tool.poetry.dependencies] pendulum = "^1.4"
As you can see, it takes a mapping of package names and version constraints.
Poetry uses this information to search for the right set of files in package "repositories" that you register
tool.poetry.repositories section, or on PyPI by default.
Also, instead of modifying the
pyproject.toml file by hand, you can use the
$ poetry add pendulum
It will automatically find a suitable version constraint.
In our example, we are requesting the
pendulum package with the version constraint
This means any version greater or equal to 1.4.0 and less than 2.0.0 (
Please read versions for more in-depth information on versions, how versions relate to each other, and on version constraints.
To install the defined dependencies for your project, just run the
$ poetry install
When you run this command, one of two things may happen:
If you have never run the command before and there is also no
poetry.lock file present,
Poetry simply resolves all dependencies listed in your
pyproject.toml file and downloads the latest version of their files.
When Poetry has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the
locking the project to those specific versions.
You should commit the
poetry.lock file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below).
This brings us to the second scenario. If there is already a
poetry.lock file as well as a
when you run
poetry install, it means either you ran the
install command before,
or someone else on the project ran the
install command and committed the
poetry.lock file to the project (which is good).
Either way, running
install when a
poetry.lock file is present resolves and installs all dependencies that you listed in
but Poetry uses the exact versions listed in
poetry.lock to ensure that the package versions are consistent for everyone working on your project.
As a result you will have all dependencies requested by your
but they may not all be at the very latest available versions
(some of the dependencies listed in the
poetry.lock file may have released newer versions since the file was created).
This is by design, it ensures that your project does not break because of unexpected changes in dependencies.
poetry.lock file to version control
Committing this file to VC is important because it will cause anyone who sets up the project to use the exact same versions of the dependencies that you are using. Your CI server, production machines, other developers in your team, everything and everyone runs on the same dependencies, which mitigates the potential for bugs affecting only some parts of the deployments. Even if you develop alone, in six months when reinstalling the project you can feel confident the dependencies installed are still working even if your dependencies released many new versions since then. (See note below about using the update command.)
Note: For libraries it is not necessary to commit the lock file.
Updating dependencies to their latest versions
As mentioned above, the
poetry.lock file prevents you from automatically getting the latest versions
of your dependencies.
To update to the latest versions, use the
$ poetry update
This will fetch the latest matching versions (according to your
and update the lock file with the new versions.
(This is equivalent to deleting the
poetry.lock file and running
Note: Poetry will display a Warning when executing an install command if
pyproject.toml are not synchronized.
Poetry and virtualenvs
When you execute the
install command (or any other "install" commands like
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.
If you're interested in what kind of shell is used here, it's fish! You can play with it in our fish shell playground.
You can also improve this playground or create your own. Please send a PR or open an issue in github.com/rootnroll/library.