Dependency specification
Dependency specification#
Dependencies for a project can be specified in various forms, which depend on the typeof the dependency and on the optional constraints that might be needed for it to be installed.
project.dependencies andtool.poetry.dependencies#
Prior Poetry 2.0, dependencies had to be declared in thetool.poetry.dependenciessection of thepyproject.toml file.
[tool.poetry.dependencies]requests="^2.13.0"With Poetry 2.0, you should consider using theproject.dependencies section instead.
[project]# ...dependencies=["requests (>=2.23.0,<3.0.0)"]While dependencies intool.poetry.dependencies are specified using toml tables,dependencies inproject.dependencies are specified as strings accordingtoPEP 508.
In many cases,tool.poetry.dependencies can be replaced withproject.dependencies.However, there are some cases where you might still need to usetool.poetry.dependencies.For example, if you want to define additional information that is not required for buildingbut only for locking (for example, an explicit source), you can enrich dependencyinformation in thetool.poetry section.
[project]# ...dependencies=["requests>=2.13.0",][tool.poetry.dependencies]requests={source="private-source"}When both are specified,project.dependencies are used for metadata when building the project,tool.poetry.dependencies is only used to enrichproject.dependencies for locking.
Alternatively, you can adddependencies todynamic and define your dependenciescompletely in thetool.poetry section. Using only thetool.poetry section mightmake sense in non-package mode when you will not build an sdist or a wheel.
[project]# ...dynamic=["dependencies"][tool.poetry.dependencies]requests={version=">=2.13.0",source="private-source"}tool.poetry.dependencies are relative path dependenciessinceproject.dependencies only support absolute paths.project section.OtherDependency groupsmust still be specified in thetool.poetry section.Version constraints#
Compatible release requirements#
Compatible release requirements specify a minimal version with the ability to update to later versions of the same level.For example, if you specify a major, minor, and patch version, only patch-level changes are allowed.If you only specify a major, and minor version, then minor- and patch-level changes are allowed.
~=1.2.3 is an example of a compatible release requirement.
| Requirement | Versions allowed |
|---|---|
| ~=1.2.3 | >=1.2.3 <1.3.0 |
| ~=1.2 | >=1.2.0 <2.0.0 |
Wildcard requirements#
Wildcard requirements allow for the latest (dependency-dependent) version where the wildcard is positioned.
*,1.* and1.2.* are examples of wildcard requirements.
| Requirement | Versions allowed |
|---|---|
| * | >=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:
>= 1.2.0> 1< 2!= 1.2.3Multiple requirements#
Multiple version requirements can also be separated with a comma, e.g.>= 1.2, < 1.5.
Exact requirements#
You can specify the exact version of a package.
1.2.3 is an example of an exact version specification.
This will tell Poetry to install this version and this version only.If other dependencies require a different version, the solver will ultimately fail and abort any installation or update procedures.
Exact versions can also be specified with== according toPEP 440.
==1.2.3 is an example of this.
Caret requirements#
Not supported inproject.dependencies.
When usingpoetry add such constraints are automatically converted into an equivalent constraint.
Caret requirements allowSemVer 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. For instance, if we previously ranpoetry add requests@^2.13.0 and wanted to update the library and ranpoetry update requests, poetry would update us to version2.14.0 if it was available, but would not update us to3.0.0. If instead, we had specified the version string as^0.1.13, poetry would update to0.1.14 but not0.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:
| Requirement | Versions allowed |
|---|---|
| ^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#
Not supported inproject.dependencies.
When usingpoetry add such constraints are automatically converted into an equivalent constraint.
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 allowed.
~1.2.3 is an example of a tilde requirement.
| Requirement | Versions allowed |
|---|---|
| ~1.2.3 | >=1.2.3 <1.3.0 |
| ~1.2 | >=1.2.0 <1.3.0 |
| ~1 | >=1.0.0 <2.0.0 |
Using the@ operator#
When adding dependencies viapoetry add, you can use the@ operator.This is understood similarly to the== syntax, but also allows prefixing anyspecifiers that are valid inpyproject.toml. For example:
poetry add"django@^4.0.0"The above would translate to the following entry inpyproject.toml:
[project]# ...dependencies=["django (>=4.0.0,<5.0.0)",][tool.poetry.dependencies]django="^4.0.0"The special keywordlatest is also understood by the@ operator:
poetry add django@latestThe above would translate to the following entry inpyproject.toml, assuming the latest release ofdjango is5.1.3:
[project]# ...dependencies=["django (>=5.1.3,<6.0.0)",][tool.poetry.dependencies]django="^5.1.3"Extras#
Extras and@ can be combined as one might expect (package[extra]@version):
poetry add django[bcrypt]@^4.0.0git dependencies#
To depend on a library located in agit repository,the minimum information you need to specify is the location of the repository:
[project]# ...dependencies=["requests @ git+https://github.com/requests/requests.git",]In thetool.poetry section you use thegit key:
[tool.poetry.dependencies]requests={git="https://github.com/requests/requests.git"}Since we haven’t specified any other information,Poetry assumes that we intend to use the latest commit on themain branchto build our project.
You can explicitly specify which branch, commit hash or tagged ref should be usd:
Append the information to the git url.
[project]# ...dependencies=["requests @ git+https://github.com/requests/requests.git@next","flask @ git+https://github.com/pallets/flask.git@38eb5d3b","numpy @ git+https://github.com/numpy/numpy.git@v0.13.2",]Combine thegit key with thebranch,rev ortag key respectively.
[tool.poetry.dependencies]# Get the latest revision on the branch named "next"requests={git="https://github.com/kennethreitz/requests.git",branch="next"}# Get a revision by its commit hashflask={git="https://github.com/pallets/flask.git",rev="38eb5d3b"}# Get a revision by its tagnumpy={git="https://github.com/numpy/numpy.git",tag="v0.13.2"}It’s possible to add a package that is located in a subdirectory of the VCS repository.
Provide the subdirectory as a URL fragment similarly to whatpip provides.
[project]# ...dependencies=["subdir_package @ git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir"]Use thesubdirectory key in thetool.poetry section:
[tool.poetry.dependencies]# Install a package named `subdir_package` from a folder called `subdir` within the repositorysubdir_package={git="https://github.com/myorg/mypackage_with_subdirs.git",subdirectory="subdir"}The correspondingadd call looks like this:
poetry add"git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir"To use an SSH connection, for example, in the case of private repositories, use the following example syntax:
[project]# ...dependencies=["pendulum @ git+ssh://git@github.com/sdispater/pendulum.git"][tool.poetry.dependencies]pendulum={git="git@github.com/sdispater/pendulum.git"}Credentials for git dependencies#
To use HTTP basic authentication with your git repositories, you can configure credentials similar tohowrepository credentials are configured.
poetry config repositories.git-org-project https://github.com/org/project.gitpoetry config http-basic.git-org-project username tokenpoetry add git+https://github.com/org/project.gitThe default git client used isDulwich.
We fall back to legacy system git client implementation in cases wheregitcredentials is used. This fallback will be removed ina future release wheregitcredentials helpers can be better supported natively.
In cases where you encounter issues with the default implementation, you may wish toexplicitly configure the use of the system git client via a shell subprocess call.
poetry config system-git-clienttruepath dependencies#
In theproject section, you can only use absolute paths:
[project]# directorydependencies=["my-package @ file:///absolute/path/to/my-package"]# filedependencies=["my-package @ file:///absolute/path/to/my-package/dist/my-package-0.1.0.tar.gz"]To depend on a library located in a local directory or file,you can use thepath property:
[tool.poetry.dependencies]# directorymy-package={path="../my-package/",develop=true}# filemy-package={path="../my-package/dist/my-package-0.1.0.tar.gz"}To install directory path dependencies in editable mode, use thedevelop keyword and set it totrue.
url dependencies#
url dependencies are libraries located on a remote archive.
[project]# ...dependencies=["my-package @ https://example.com/my-package-0.1.0.tar.gz"]Use theurl property.
[tool.poetry.dependencies]# directorymy-package={url="https://example.com/my-package-0.1.0.tar.gz"}The correspondingadd call is:
poetry add https://example.com/my-package-0.1.0.tar.gzDependencyextras#
You can specifyPEP-508 Extrasfor a dependency as shown here.
[project]# ...dependencies=["gunicorn[gevent] (>=20.1,<21.0)"][tool.poetry.dependencies]gunicorn={version="^20.1",extras=["gevent"]}extras.source dependencies#
project section.To depend on a package from analternate repository,you can use thesource property:
[[tool.poetry.source]]name="foo"url="https://foo.bar/simple/"priority="supplemental"[tool.poetry.dependencies]my-cool-package={version="*",source="foo"}with the correspondingadd call:
poetry add my-cool-package --source foofoo to be configured correctly. Seeusing a private repositoryfor further information.Python restricted dependencies#
You can also specify that a dependency should be installed only for specific Python versions:
[project]# ...dependencies=["tomli (>=2.0.1,<3.0) ; python_version < '3.11'","pathlib2 (>=2.2,<3.0) ; python_version >= '3.9' and python_version < '4.0'"][tool.poetry.dependencies]tomli={version="^2.0.1",python="<3.11"}pathlib2={version="^2.2",python="^3.9"}Using environment markers#
If you need more complex install conditions for your dependencies,Poetry supportsenvironment markers:
[project]# ...dependencies=["pathlib2 (>=2.2,<3.0) ; python_version <= '3.4' or sys_platform == 'win32'"]Use themarkers property:
[tool.poetry.dependencies]pathlib2={version="^2.2",markers="python_version <= '3.4' or sys_platform == 'win32'"}extra environment marker#
Poetry populates theextra marker with each of the selected extras of the root package.For example, consider the following dependency:
[project.optional-dependencies]paths=["pathlib2 (>=2.2,<3.0) ; sys_platform == 'win32'"]pathlib2 will be installed when you install your package with--extras paths on awin32 machine.
Exclusive extras#
The first example will only work completely if you configure Poetry to not re-resolve for installation:
poetry config installer.re-resolvefalseThis is a new feature of Poetry 2.0 that may become the default in a future version of Poetry.
Keep in mind that all combinations of possible extras available in your project need to be compatible with each other.This means that in order to use differing or incompatible versions across different combinations, you need to make yourextra markersexclusive. For example, the following installs PyTorch from one source repository with CPU versionswhen thecuda extra isnot specified, while the other installs from another repository with a separate version setfor GPUs when thecuda extrais specified:
[project]name="torch-example"requires-python=">=3.10"dependencies=["torch (==2.3.1+cpu) ; extra != 'cuda'",][project.optional-dependencies]cuda=["torch (==2.3.1+cu118)",][tool.poetry]package-mode=false[tool.poetry.dependencies]torch=[{markers="extra != 'cuda'",source="pytorch-cpu"},{markers="extra == 'cuda'",source="pytorch-cuda"},][[tool.poetry.source]]name="pytorch-cpu"url="https://download.pytorch.org/whl/cpu"priority="explicit"[[tool.poetry.source]]name="pytorch-cuda"url="https://download.pytorch.org/whl/cu118"priority="explicit"For the CPU case, we have to specify"extra != 'cuda'" because the version specified is not compatible with theGPU (cuda) version.
This same logic applies when you want either-or extras:
[project]name="torch-example"requires-python=">=3.10"[project.optional-dependencies]cpu=["torch (==2.3.1+cpu)",]cuda=["torch (==2.3.1+cu118)",][tool.poetry]package-mode=false[tool.poetry.dependencies]torch=[{markers="extra == 'cpu' and extra != 'cuda'",source="pytorch-cpu"},{markers="extra == 'cuda' and extra != 'cpu'",source="pytorch-cuda"},][[tool.poetry.source]]name="pytorch-cpu"url="https://download.pytorch.org/whl/cpu"priority="explicit"[[tool.poetry.source]]name="pytorch-cuda"url="https://download.pytorch.org/whl/cu118"priority="explicit"Multiple constraints dependencies#
Sometimes, one of your dependencies may have different version ranges dependingon the target Python versions.
Let’s say you have a dependency on the packagefoo which is only compatiblewith Python 3.6–3.7 up to version 1.9, and compatible with Python 3.8+ from version 2.0:you would declare it like so:
[project]# ...dependencies=["foo (<=1.9) ; python_version >= '3.6' and python_version < '3.8'","foo (>=2.0,<3.0) ; python_version >= '3.8'"][tool.poetry.dependencies]foo=[{version="<=1.9",python=">=3.6,<3.8"},{version="^2.0",python=">=3.8"}]python)otherwise it will cause an error when resolving dependencies.Combining git / url / path dependencies with source repositories#
Direct origin (git/url/path) dependencies can satisfy the requirement of a dependency thatdoesn’t explicitly specify a source, even when mutually exclusive markers are used. For instance,in the following example, the url package will also be a valid solution for the second requirement:
foo=[{platform="darwin",url="https://example.com/example-1.0-py3-none-any.whl"},{platform="linux",version="^1.0"},]Sometimes you may instead want to use a direct origin dependency for specific conditions(i.e., a compiled package that is not available on PyPI for a certain platform/architecture) whilefalling back on source repositories in other cases. In this case you should explicitly ask for yourdependency to be satisfied by anothersource. For example:
foo=[{platform="darwin",url="https://example.com/foo-1.0.0-py3-none-macosx_11_0_arm64.whl"},{platform="linux",version="^1.0",source="pypi"},]Expanded dependency specification syntax#
In the case of more complex dependency specifications, you may find that youend up with lines which are very long and difficult to read. In these cases,you can shift from using “inline table” syntax to the “standard table” syntax.
An example where this might be useful is the following:
[tool.poetry.group.dev.dependencies]black={version="19.10b0",allow-prereleases=true,python="^3.7",markers="platform_python_implementation == 'CPython'"}As a single line, this is a lot to digest. To make this a bit easier towork with, you can do the following:
[tool.poetry.group.dev.dependencies.black]version="19.10b0"allow-prereleases=truepython="^3.7"markers="platform_python_implementation == 'CPython'"The same information is still present, and ends up providing the exactsame specification. It’s simply split into multiple, slightly more readable,lines.
Handling of pre-releases#
Per default, Poetry will prefer stable releases and only choose a pre-releaseif no stable release satisfies a version constraint. In some cases, this may result ina solution containing pre-releases even if another solution without pre-releases exists.
If you want to disallow pre-releases for a specific dependency,you can setallow-prereleases tofalse. In this case, dependency resolution willfail if there is no solution without choosing a pre-release.
If you want to prefer the latest version of a dependency even if it is a pre-release,you can setallow-prereleases totrue so that Poetry makes no distinctionbetween stable and pre-release versions during dependency resolution.