skip to navigation
skip to content

poetry 0.5.0b1

Python dependency management and packaging made easy.

Latest Version: 0.6.3

Poetry: Dependency Management for Python

.. figure::
:alt: Poetry build status

Poetry build status

Poetry helps you declare, manage and install dependencies of Python
projects, ensuring you have the right stack everywhere.

.. figure::
:alt: Poet Install

Poet Install

The package is **highly experimental** at the moment so expect things to
change and break. However, if you feel adventurous feedback and pull
requests are greatly appreciated.

Also, be aware that the features described here are the goal that this
library is aiming for and, as of now, not all of them are implemented
(but most of them are). The dependency management is done while the
packaging and publishing are still at the beginning.

And finally, Poetry's code is only compatible with Python 3.6+ but it
can manage Python project's with previous versions without any problem.


.. code:: bash

pip install poetry

Enable tab completion for Bash, Fish, or Zsh

``poetry`` supports generating completion scripts for Bash, Fish, and
Zsh. See ``poet help completions`` for full details, but the gist is as
simple as using one of the following:

.. code:: bash

# Bash
poetry completions bash > /etc/bash_completion.d/pyproject.bash-completion

# Bash (macOS/Homebrew)
poetry completions bash > $(brew --prefix)/etc/bash_completion.d/pyproject.bash-completion

# Fish
poetry completions fish > ~/.config/fish/completions/

# Zsh
poetry completions zsh > ~/.zfunc/_poetry

*Note:* you may need to restart your shell in order for the changes to
take effect.

For ``zsh``, you must then add the following line in your ``~/.zshrc``
before ``compinit``:

.. code:: zsh



``poetry`` is a tool to handle dependencies installation, building and
packaging of Python packages. It only needs one file to do all of that:
the new, `standardized <https:"" dev="" peps="" pep-0518=""/>`__

.. code:: toml

name = "my-package"
version = "0.1.0"
description = "The description of the package"

license = "MIT"

authors = [
"Sébastien Eustace <>"

readme = ''

repository = ""
homepage = ""

keywords = ['packaging', 'poetry']

python = "~2.7 || ^3.2" # Compatible python versions must be declared here
toml = "^0.9"
# Dependencies with extras
requests = { version = "^2.13", extras = [ "security" ] }
# Python specific dependencies with prereleases allowed
pathlib2 = { version = "^2.2", python = "~2.7", allows_prereleases = true }
# Git dependencies
cleo = { git = "", branch = "master" }

# Optional dependencies (extras)
pendulum = { version = "^1.4", optional = true }

pytest = "^3.0"
pytest-cov = "^2.4"

my-script = 'my_package:main'

There are some things we can notice here:

- It will try to enforce `semantic versioning <http:"">`__ as
the best practice in version naming.
- You can specify the readme, included and excluded files: no more
````. ``poetry`` will also use VCS ignore files (like
``.gitignore``) to populate the ``exclude`` section.
- Keywords (up to 5) can be specified and will act as tags on the
packaging site.
- The dependencies sections support caret, tilde, wildcard, inequality
and multiple requirements.
- You must specify the python versions for which your package is

``poetry`` will also detect if you are inside a virtualenv and install
the packages accordingly. So, ``poetry`` can be installed globally and
used everywhere.

``poetry`` also comes with a full fledged dependency resolution library,
inspired by `Molinillo <https:"" cocoapods="" molinillo="">`__.


Packaging system and dependency management in Python is 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: ````, ``requirements.txt``, ``setup.cfg``,
```` and the newly added ``Pipfile``.

So I wanted a tool that would limit everything to a single configuration
file to do: dependency management, packaging and publishing.

It takes inspiration in tools that exist in other languages, like
``composer`` (PHP) or ``cargo`` (Rust).

And, finally, there is no reliable tool to properly resolves
dependencies in Python, so I started ``poetry`` to bring an exhaustive
depency resolver to the Python community.

What about Pipenv?

In short: I do not like the CLI it provides, or some of the decisions
made, and I think we can do a better and more intuitive one. Here are a
few things that I don't like.

Dependency resolution

The dependency resolution is erratic and will fail even is there is a
solution. Let's take an example:

.. code:: bash

pipenv install oslo.utils==1.4.0

will fail with this error:

.. code:: text

Could not find a version that matches pbr!=0.7,!=2.1.0,<1.0,>=0.6,>=2.0.0

while Poetry will get you the right set of packages:

.. code:: bash

poetry add oslo.utils=1.4.0

results in :

.. code:: text

- Installing pytz (2018.3)
- Installing netifaces (0.10.6)
- Installing netaddr (0.7.19)
- Installing oslo.i18n (2.1.0)
- Installing iso8601 (0.1.12)
- Installing six (1.11.0)
- Installing babel (2.5.3)
- Installing pbr (0.11.1)
- Installing oslo.utils (1.4.0)

Install command

When you specify a package to the ``install`` command it will add it as
a wildcard dependency. This means that **any** version of this package
can be installed which can lead to compatibility issues.

Also, you have to explicitely tell it to not update the locked packages
when you installed new ones. This should be the default.

Remove command

The ``remove`` command will only remove the package specified but not
its dependencies if they are no longer needed.

You either have to use ``sync`` or ``clean`` to fix that.

Too limited in scope

Finally, the ``Pipfile`` is just a replacement from ``requirements.txt``
and, in the end, you will still need to populate your ```` file
(or ``setup.cfg``) with the exact same dependencies you declared in your
``Pipfile``. So, in the end, you will still need to manage a few
configuration files to properly setup your project.



This command will help you kickstart your new Python project by creating
a directory structure suitable for most projects.

.. code:: bash

poetry new my-package

will create a folder as follows:

.. code:: text

├── pyproject.toml
├── README.rst
├── my_package
└── tests
└── test_my_package

If you want to name your project differently than the folder, you can
pass the ``--name`` option:

.. code:: bash

poetry new my-folder --name my-package


The ``install`` command reads the ``pyproject.toml`` file from the
current directory, resolves the dependencies, and installs them.

.. code:: bash

poetry install

If there is a ``pyproject.lock`` file in the current directory, it will
use the exact versions from there instead of resolving them. This
ensures that everyone using the library will get the same versions of
the dependencies.

If there is no ``pyproject.lock`` file, Poetry will create one after
dependency resolution.

You can specify to the command that you do not want the development
dependencies installed by passing the ``--no-dev`` option.

.. code:: bash

poetry install --no-dev

You can also specify the extras you want installed by passing the
``--E|--extras`` option (See `Extras <#extras>`__ for more info)

.. code:: bash

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql


- ``--no-dev``: Do not install dev dependencies.
- ``-E|--extras``: Features to install (multiple values allowed).


In order to get the latest versions of the dependencies and to update
the ``pyproject.lock`` file, you should use the ``update`` command.

.. code:: bash

poetry update

This will resolve all dependencies of the project and write the exact
versions into ``pyproject.lock``.

If you just want to update a few packages and not all, you can list them
as such:

.. code:: bash

poetry update requests toml


- ``--dry-run`` : Outputs the operations but will not execute anything
(implicitly enables --verbose).


The ``add`` command adds required packages to your ``pyproject.toml``
and installs them.

If you do not specify a version constraint, poetry will choose a
suitable one based on the available package versions.

.. code:: bash

poetry add requests pendulum


- ``--D|dev``: Add package as development dependency.
- ``--optional`` : Add as an optional dependency.
- ``--dry-run`` : Outputs the operations but will not execute anything
(implicitly enables --verbose).


The ``remove`` command removes a package from the current list of
installed packages

.. code:: bash

poetry remove pendulum


- ``--D|dev``: Removes a package from the development dependencies.
- ``--dry-run`` : Outputs the operations but will not execute anything
(implicitly enables --verbose).


To list all of the available packages, you can use the ``show`` command.

.. code:: bash

poetry show

If you want to see the details of a certain package, you can pass the
package name.

.. code:: bash

poetry show pendulum

name : pendulum
version : 1.4.2
description : Python datetimes made easy

- python-dateutil >=2.6.1
- tzlocal >=1.4
- pytzdata >=2017.2.2


- ``--tree``: List the dependencies as a tree.
- ``-l|--latest``: Show the latest version.
- ``-o|--outdated``: Show the latest version but only for packages that
are outdated.


The ``build`` command builds the source and wheels archives.

.. code:: bash

poetry build

Note that, at the moment, only pure python wheels are supported.


- ``-F|--format``: Limit the format to either wheel or sdist.


This command builds (if not already built) and publishes the package to
the remote repository.

It will automatically register the package before uploading if this is
the first time it is submitted.

.. code:: bash

poetry publish


- ``-r|--repository``: The repository to register the package to
(default: ``pypi``). Should match a repository name set by the
```config`` <#config>`__ command.


The ``config`` command allows you to edit poetry config settings and

.. code:: bash

poetry config --list


.. code:: bash

poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

``setting-key`` is a configuration option name and ``setting-value1`` is
a configuration value.

Modifying repositories

In addition to modifying the config section, the config command also
supports making changes to the repositories section by using it the
following way:

.. code:: bash

poetry config

This will set the url for repository ``foo`` to

If you want to store your credentials for a specific repository, you can
do so easily:

.. code:: bash

poetry config username password

If you do not specify the password you will be prompted to write it.


- ``--unset``: Remove the configuration element named by
- ``--list``: Show the list of current config variables.


This command searches for packages on a remote index.

.. code:: bash

poetry search requests pendulum


- ``-N|--only-name``: Search only in name.


This command locks (without installing) the dependencies specified in

.. code:: bash

poetry lock

The ``pyproject.toml`` file

The ``tool.poetry`` section of the ``pyproject.toml`` file is composed
of multiple sections.


The name of the package. **Required**


The version of the package. **Required**

This should follow `semantic versioning <http:""/>`__. However
it will not be enforced and you remain free to follow another


A short description of the package. **Required**


The license of the package.

The recommended notation for the most common licenses is (alphabetical):

- Apache-2.0
- BSD-2-Clause
- BSD-3-Clause
- BSD-4-Clause
- GPL-2.0
- GPL-2.0+
- GPL-3.0
- GPL-3.0+
- LGPL-2.1
- LGPL-2.1+
- LGPL-3.0
- LGPL-3.0+

Optional, but it is highly recommended to supply this. More identifiers
are listed at the `SPDX Open Source License
Registry <https:"" licenses=""/>`__.


The authors of the package. This is a list of authors and should contain
at least one author.

Authors must be in the form ``name <email>``.


The readme file of the package. **Required**

The file can be either ``README.rst`` or ````. If it's a
markdown file you have to install the
`pandoc <https:"" jgm="" pandoc="">`__ utility so that it can be
automatically converted to a RestructuredText file.

You also need to have the
`pypandoc <https:"" pypi="" pypandoc=""/>`__ package installed.
If you install ``poet`` via ``pip`` you can use the ``markdown-readme``
extra to do so.

.. code:: bash

pip install pypoet[markdown-readme]


An URL to the website of the project. **Optional**


An URL to the repository of the project. **Optional**


An URL to the documentation of the project. **Optional**


A list of keywords (max: 5) that the package is related to. **Optional**

include and exclude

A list of patterns that will be included in the final package.

You can explicitly specify to Poet that a set of globs should be ignored
or included for the purposes of packaging. The globs specified in the
exclude field identify a set of files that are not included when a
package is built.

If a VCS is being used for a package, the exclude field will be seeded
with the VCS’ ignore settings (``.gitignore`` for git for example).

.. code:: toml

# ...
include = ["package/**/*.py", "package/**/.c"]

.. code:: toml

exclude = ["package/"]

``dependencies`` and ``dev-dependencies``

Poetry is configured to look for dependencies on
`PyPi <https:"">`__ by default. Only the name and a version
string are required in this case.

.. code:: toml

requests = "^2.13.0"

If you want to use a private repository, you can add it to your
``pyproject.toml`` file, like so:

.. code:: toml

name = 'private'
url = ''

Be aware that declaring the python version for which your package is
compatible is mandatory:

.. code:: toml

python = "^3.6"

Caret requirement

**Caret requirements** allow SemVer compatible updates to a specified
version. An update is allowed if the new version number does not modify
the left-most non-zero digit in the major, minor, patch grouping. In
this case, if we ran ``poetry update requests``, poetry would update us
to version ``2.14.0`` if it was available, but would not update us to
``3.0.0``. If instead we had specified the version string as
``^0.1.13``, poetry would update to ``0.1.14`` but not ``0.2.0``.
``0.0.x`` is not considered compatible with any other version.

Here are some more examples of caret requirements and the versions that
would be allowed with them:

.. code:: text

^1.2.3 := >=1.2.3 <2.0.0
^1.2 := >=1.2.0 <2.0.0
^1 := >=1.0.0 <2.0.0
^0.2.3 := >=0.2.3 <0.3.0
^0.0.3 := >=0.0.3 <0.0.4
^0.0 := >=0.0.0 <0.1.0
^0 := >=0.0.0 <1.0.0

Tilde requirements

**Tilde requirements** specify a minimal version with some ability to
update. If you specify a major, minor, and patch version or only a major
and minor version, only patch-level changes are allowed. If you only
specify a major version, then minor- and patch-level changes are

``~1.2.3`` is an example of a tilde requirement.

.. code:: text

~1.2.3 := >=1.2.3 <1.3.0
~1.2 := >=1.2.0 <1.3.0
~1 := >=1.0.0 <2.0.0

Wildcard requirements

**Wildcard requirements** allow for any version where the wildcard is

``*``, ``1.*`` and ``1.2.*`` are examples of wildcard requirements.

.. code:: text

* := >=0.0.0
1.* := >=1.0.0 <2.0.0
1.2.* := >=1.2.0 <1.3.0

Inequality requirements

**Inequality requirements** allow manually specifying a version range or
an exact version to depend on.

Here are some examples of inequality requirements:

.. code:: text

>= 1.2.0
> 1
< 2
!= 1.2.3

Multiple requirements

Multiple version requirements can also be separated with a comma, e.g.
``>= 1.2, < 1.5``.

``git`` dependencies

To depend on a library located in a ``git`` repository, the minimum
information you need to specify is the location of the repository with
the git key:

.. code:: toml

requests = { git = "" }

Since we haven’t specified any other information, Poetry assumes that we
intend to use the latest commit on the ``master`` branch to build our
project. You can combine the ``git`` key with the ``rev``, ``tag``, or
``branch`` keys to specify something else. Here's an example of
specifying that you want to use the latest commit on a branch named

.. code:: toml

requests = { git = "", branch = "next" }

Python restricted dependencies

You can also specify that a dependency should be installed only for
specific Python versions:

.. code:: toml

pathlib2 = { version = "^2.2", python = "~2.7" }

.. code:: toml

pathlib2 = { version = "^2.2", python = ["~2.7", "^3.2"] }


This section describe the scripts or executable that will be installed
when installing the package

.. code:: toml

poetry = ''

Here, we will have the ``poetry`` script installed which will execute
```` in the ``poetry`` package.


Poetry supports extras to allow expression of:

- optional dependencies, which enhance a package, but are not required;
- clusters of optional dependencies.

.. code:: toml

name = "awesome"

# These packages are mandatory and form the core of this package’s distribution.
mandatory = "^1.0"

# A list of all of the optional dependencies, some of which are included in the
# below `extras`. They can be opted into by apps.
psycopg2 = { version = "^2.7", optional = true }
mysqlclient = { version = "^1.3", optional = true }

mysql = ["mysqlclient"]
pgsql = ["psycopg2"]

When installing packages, you can specify extras by using the
``-E|--extras`` option:

.. code:: bash

poet install --extras "mysql pgsql"
poet install -E mysql -E pgsql


Poetry supports arbitrary plugins wich work similarly to `setuptools
points <http:"" en="" latest="" setuptools.html="">`__.
To match the example in the setuptools documentation, you would use the

.. code:: toml

[plugins] # Optional super table

".rst" = "some_module::SomeClass"


- `Official Website <https:"">`__
- `Issue Tracker <https:"" sdispater="" poetry="" issues="">`__
File Type Py Version Uploaded on Size
poetry-0.5.0b1-py3-none-any.whl (md5) Python Wheel py3 2018-03-14 414KB
poetry-0.5.0b1.tar.gz (md5) Source 2018-03-14 104KB