Dependency version syntax for Python Poetry

Question

The Poetry project is a dependency management system for Python. It uses the new pyproject.toml file as its config file.

The Poetry tools supports a few different ways of specifying the allowed versions of your dependencies. What is the syntax of the version specifier for Poetry dependencies?

Answer 1

In pyproject.toml, you use the [tool.poetry.dependencies] and [tool.poetry.dev-dependencies] sections to specify your dependencies by name and version.

When you run poetry install, Poetry will install the exact hashed requirements that it has written to its poetry.lock file.

However, when you run poetry update, Poetry will check to see if it can find newer versions of your dependencies that match the version criteria you specified. If poetry update finds a newer version that is allowed by your version specifiers, it will download and install it. It will also update its poetry.lock file with the new version number and the new hash.

Poetry supports several different ways of declaring the allowed version of your dependencies.

Exact Version

If you don't include any modifiers, Poetry will keep your dependency pinned at that exact version.

beepboop = "2.1.7" 

With that configuration, if a new version of beepboop is released, poetry update will not install it.

Caret Version

If you use the caret ^ character, Poetry will update to any new version that does not change the leftmost non-zero section.

beepboop = "^2.1.7" # Equivalent to >=2.1.7, <3.0.0 

With the configuration above, poetry update would update beepboop to 2.1.8, 2.2, 2.3, etc. Poetry would not update to beepboop 3.0, because that changes the leftmost non-zero section of the version number from 2 to 3.

zeepzorp = "^0.24.1" # Equivalent to >=0.24.1, <0.25.0 

With the configuration above, poetry update would update zeepzorp to 0.24.2. Poetry would not update to zeepzorp 0.25.0, because that changes the leftmost non-zero section of the version number from 24 to 25.

The caret version modifier is pretty aggressive about which upgraded versions are allowed. This can cause problems if the maintainers of your dependencies introduce breaking changes without incrementing the major version number.

Tilde Version

The tilde ~ character tells Poetry to allow minor updates. If you specify a major, minor, and patch version, only patch-level changes are allowed. If you specify a major and minor version, again only patch-level changes are allowed. If you specify only a major version, then minor- and patch-level changes are allowed.

beepboop = "~2.1.7" # Equivalent to >=2.1.7, <2.2.0  beepboop = "~2.1" # Equivalent to >=2.1.0, <2.2.0  beepboop = "~2" # Equivalent to >=2.0.0, <3.0.0 

The tilde version modifier is less aggressive than the caret version modifier in the upgrades it will allow.

Wildcard Version

The star * character is a wildcard. Any version number is allowed at the wildcard position.

beepboop = "2.1.*" # Equivalent to >=2.1.0, <2.2.0  beepboop = "2.*" # Equivalent to >=2.0.0, <3.0.0  beepboop = "*" # Allows any version. Equivalent to >=0.0.0   

Inequality Version

You can use inequalities to specify allowed version ranges. Some examples:

beepboop = ">= 1.2.0" beepboop = "> 1" beepboop = "< 2" beepboop = "!= 1.2.3" 

Multiple Version Specifiers

You can define ranges of allowed versions by using multiple inequalities, separated by commas.

beepboop = ">= 1.2, < 1.5, !=1.2.2" 

SolverProblemError

If you hand-edited your pyproject.toml file and you are getting a SolverProblemError, try using the poetry add command instead.

For example, I tried adding mypy = "^0.670" to my pyproject.toml and got a solver error. The poetry add command formatted the file the way poetry wanted, and specified the dependency as mypy = "^0.670.0".

You can also get a SolverProblemError if you specify your python version as '*' in pyproject.toml. Try specifying your python version more narrowly, such as "^3.6". See this GitHub issue for more info.

References

https://python-poetry.org/docs/dependency-specification/

https://github.com/sdispater/poetry#dependencies-and-dev-dependencies