This new version brings a brand new official installer, dependency resolver improvements, virtualenv management and detection improvements and many more small improvements and bug fixes.

There are some breaking changes in this release, especially in the way Poetry resolves dependencies, so before upgrading you should read the following release notes

New features

Brand new installer

A lot of issues on the official issue tracker were related to the installation of Poetry: bugs, permission errors and overall confusion about the way Poetry should be installed.

As of this release, the installer will install Poetry in an isolated way in the home directory of the current user.

You only need to install Poetry once. It will automatically pick up the current Python version and use it to create virtualenvs accordingly. This works particularly well with a tool like pyenv which allows to easily switch between Python versions.

The installer installs the poetry tool to Poetry's bin directory. On Unix it is located at $HOME/.poetry/bin and on Windows at %USERPROFILE%\.poetry\bin .

This directory will be in your $PATH environment variable, which means you can run them from the shell without further configuration. Open a new shell and type the following:

poetry --version

If you see something like Poetry 0.12.0 then you are ready to use Poetry. If you decide Poetry isn't your thing, you can completely remove it from your system by running the installer again with the --uninstall option.

You can still install Poetry by alternative ways if you want, see the documentation for more information.

It is not possible to use the self:update command to upgrade Poetry from 0.11.5 to 0.12 . Use the installer to upgrade.

Dependency resolution improvements

The dependency resolver has been improved and fixed. However, these necessary changes came at the cost of backward compatibility.

Basically, a package would be accepted even if its Python requirement was not compatible with the root package requirement.

Let's take an example: ipython . From version 6.0 and onwards it's only compatible with Python >=3.3, so if your project depends on Python ~2.7 || ^3.6 , ipython>=6.0 should not be selected for locking but due to a bug in the previous versions it would, causing errors later on in the installation process.

Now, the proper ipython (5.8.0) version will be selected.

But this required a change in the behavior of the resolver which can cause issues temporarily until you update your pyproject.toml file to take into account these changes.

The biggest of these changes is that a wildcard dependency on python will now be interpreted as ~2.7 || ^3.4 which match the currently maintained Python versions. If that is not what you want, change the python dependency constraint to what matches what you actually want.

Note that this is only to help the resolver and avoid conflict detection errors. This does not affect the packaging process where a wildcard Python dependency will still be respected.

Another important change is the conflict detection on conditional dependencies. Let's take an example:

The root project is compatible with Python ^3.5 .

. The root project depends on ccxt .

. The latest versions of ccxt depends on aiohttp >=3.0.1 for Python >=3.5.2 .

depends on for . However, every version of aiohttp >=3.0.1 requires Python >=3.5.3 .

requires . This is a conflict because this would leave an uncertainty for Python 3.5.2 if we were to choose any version of aiohttp >=3.0.1

In previous versions, this would fail but now the resolver sees something is wrong and will try to find a version that satisfies everything (after a lot of conflict resolution and a long time, here is why).

To avoid this conflict resolution, it's best in this case to set the root project Python constraint to ^3.5.3 , this will help the resolver find a valid solution faster.

However, this is an issue upstream (in ccxt ) and should be fixed there.

Multiple constraints dependencies

Sometimes, one of your dependency may have different version ranges depending on the target Python versions.

Let's say you have a dependency on the package foo which is only compatible with Python <3.0 up to version 1.9 and compatible with Python 3.4+ from version 2.0: you can now declare it like so:

[tool.poetry.dependencies] foo = [ {version = "<=1.9" , python = "^2.7" } , {version = "^2.0" , python = "^3.4" } ]

The constraints must have different requirements (like python ) otherwise it will cause an error when resolving dependencies.

PEP-517 compliant build backend

PEP-517 introduces a standard way to define alternative build systems to build a Python project.

Poetry is now compliant with PEP-517 so if you use Poetry to manage your Python project you should reference it in the build-system section of the pyproject.toml file like so:

[build-system] requires = ["poetry>=0.12"] build-backend = "poetry.masonry.api"

When using the new or init command this section will be automatically added.

Lock file renamed from pyproject.lock to poetry.lock

This decision has been made to be much more explicit about where the lock file is coming from and to not use a name that is not specific to Poetry.

Note that the migration will be done automatically and does not require human intervention.

All new projects will automatically use the new poetry.lock .

Other new features

New cache version system to automatically refresh the cache on major changes, so that the end user does not need to do it manually.

Added a --lock option to update to only update the lock file without executing operations.

option to to only update the lock file without executing operations. Support for the Project-URL metadata when publishing.

metadata when publishing. Support for optional scripts.

Added a --no-dev option to show .

Changes

install command improvements and develop deprecation.

The develop command is now deprecated. You should now use the install command which, as of this release, will install the current project in editable mode.

Other changes

Improved virtualenv detection and management.

Wildcard python dependencies are now equivalent to ~2.7 || ^3.4 .

dependencies are now equivalent to . Changed behavior of the resolver for conditional dependencies.

Improved the check command.

command. Empty passwords are now supported when publishing.

Fixes