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