Specifying dependencies#
uvでは、プロジェクトの依存関係は2つのpyproject.tomlテーブル、project.dependenciesとtool.uv.sourcesにわたって宣言されます。
project.dependenciesは、標準に準拠した依存関係メタデータを定義し、PyPIへのアップロード時またはホイールの構築時に伝播されます。
tool.uv.sourcesは、開発中に組み込まれた追加のソースで依存関係メタデータを強化します。依存関係ソースは、Gitリポジトリ、URL、ローカルパス、または代替レジストリにすることができます。
tool.uv.sourcesを使用すると、uvは、project.dependencies標準でサポートされていない編集可能なインストールや相対パスなどの一般的なパターンをサポートできます。次に例を示します。:
[project]
name = "albatross"
version = "0.1.0"
dependencies = [
"bird-feeder",
]
[tool.uv.sources]
bird-feeder = { path = "./packages/bird-feeder" }
Project dependencies#
project.dependenciesテーブルは、PyPIへのアップロード時またはホイールの構築時に使用される依存関係を表します。個々の依存関係はPEP 508構文を使用して指定され、テーブルはPEP 621標準に従います。project.dependenciesは、プロジェクトに必要なパッケージのリストを定義します。
インストール時に使用されるバージョン制約。各エントリには、依存性の名前とバージョンが含まれます。エントリには、プラットフォーム固有のパッケージの追加または環境マーカーを含めることができます。次に例を示します。
[project]
name = "albatross"
version = "0.1.0"
dependencies = [
# Any version in this range
"tqdm >=4.66.2,<5",
# Exactly this version of torch
"torch ==2.2.2",
# Install transformers with the torch extra
"transformers[torch] >=4.39.3,<5",
# Only install this package on older python versions
# See "Environment Markers" for more information
"importlib_metadata >=7.1.0,<8; python_version < '3.10'",
"mollymawk ==0.1.0"
]
プロジェクトが標準パッケージインデックスからのパッケージのみを必要とする場合は、project.dependenciesで十分です。プロジェクトがGit、リモートURL、またはローカルソースからのパッケージに依存している場合は、tool.uv.sourcesを使用して、スタンド準拠のproject.dependenciesテーブルから排出することなく、依存関係メタデータを強化できます。
Dependency sources#
開発中、プロジェクトはPyPIでは利用できないパッケージに依存することがあります。uvでは、次の追加ソースがサポートされています。:
- Git:Gitリポジトリー。
- URL:リモートホイールまたはソース配布。
- Path:ローカルホイール、ソース配布、またはプロジェクトディレクトリ。
- Workspace:現在のワークスペースのメンバー。
依存関係ごとに定義できるソースは1つだけです。
非uvプロジェクトがGit-またはpath-dependencyとしてソースを持つプロジェクトを使用する場合、project.dependenciesとproject.optional-dependenciesのみが考慮されることに注意してください。ソーステーブルに提供される情報は、他のパッケージマネージャに固有の形式で再指定する必要があります。
--no-sourcesを使用すると、指定された依存関係を満たす可能性のあるworkspace membersがuvによって検出されなくなります。
--no-sourcesを使用すると、指定された依存関係を満たす可能性のあるworkspace membersがuvによって検出されなくなります。
Git#
Git依存性ソースを追加するには、クローンするGit互換のURLの前にgit+を付けます。
次に例を示します。
Will result in a pyproject.toml with:
以下を含むpyproject.tomlが作成されます。:
[project]
dependencies = [
"httpx",
]
[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx" }
リビジョン、タグ、または分岐も含めることができます。:
$ uv add git+https://github.com/encode/httpx --tag 0.27.0
$ uv add git+https://github.com/encode/httpx --branch main
$ uv add git+https://github.com/encode/httpx --rev 326b943
Gitの依存関係は、pyproject.tomlで{ git = <url> }構文を使用して手動で追加または編集することもできます。ターゲットリビジョンは、rev、tag、またはbranchのいずれかで指定できます。パッケージがリポジトリルートにない場合は、subdirectoryを指定できます。
URL#
URLソースを追加するには、wheel(.whlで終わる)またはsource distribution(.zipまたは.tar.gzで終わる)のいずれかにhttps://URLを指定します。
次に例を示します。:
$ uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"
以下を含むpyproject.tomlが作成されます。:
[project]
dependencies = [
"httpx",
]
[tool.uv.sources]
httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }
URLの依存関係は、pyproject.tomlで{ url = <url> }構文を使用して手動で追加または編集することもできます。ソースディストリビューションがアーカイブルートにない場合は、subdirectoryを指定できます。
Path#
パスソースを追加するには、wheel(.whlで終わる)、ソースディストリビューション(.zipまたは.tar.gzで終わる)、またはpyproject.tomlを含むディレクトリのパスを指定します。
次に例を示します。:
以下を含むpyproject.tomlが作成されます。:
[project]
dependencies = [
"foo",
]
[tool.uv.sources]
foo = { path = "/example/foo-0.1.0-py3-none-any.whl" }
パスは相対パスにすることもできます。:
または、プロジェクトディレクトリへのパス。:
Important
editable installationは、デフォルトではパスの依存関係に使用されません。プロジェクトディレクトリに対して編集可能なインストールが要求される場合があります:
ただし、手動パスの依存関係ではなく、workspacesを使用することをお勧めします。
Workspace member#
ワークスペース・メンバーの依存関係を宣言するには、メンバー名を{workspace=true}で追加します。すべてのワークスペース・メンバーは明示的に指定する必要があります。ワークスペース・メンバーは常にeditableです。ワークスペースの詳細は、workspaceのドキュメントを参照してください。
[project]
dependencies = [
"mollymawk ==0.1.0"
]
[tool.uv.sources]
mollymawk = { workspace = true }
[tool.uv.workspace]
include = [
"packages/mollymawk"
]
Optional dependencies#
ライブラリとして公開されるプロジェクトでは、デフォルトの依存ツリーを削減するために、いくつかの機能をオプションにすることが一般的です。たとえば、Pandasにはexcel extraとplot extraがあります。これは、明示的に必要とされない限り、Excelパーサーとmatplotlibのインストールを回避するためです。Extraはpackage [<extra>]構文で要求されます。たとえば、pandas[plot, excel]です。
オプションの依存関係は[project.optional-dependencies]で指定されます。これは、PEP 508構文に従って、追加の名前からその依存関係にマップするTOMLテーブルです。
オプションの依存関係は、通常の依存関係と同じようにtool.uv.sourcesにエントリを持つことができます。
[project]
name = "pandas"
version = "1.0.0"
[project.optional-dependencies]
plot = [
"matplotlib>=3.6.3"
]
excel = [
"odfpy>=1.4.1",
"openpyxl>=3.1.0",
"python-calamine>=0.1.7",
"pyxlsb>=1.0.10",
"xlrd>=2.0.1",
"xlsxwriter>=3.0.5"
]
オプションの依存関係を追加するには、--optional <extra>オプションを使用します。
Development dependencies#
オプションの依存関係とは異なり、開発依存関係はローカルのみであり、PyPIまたはその他のインデックスに公開されるときにプロジェクト要件に含まれません。そのため、開発依存関係は[project]ではなく[tool.uv]に含まれます。
開発依存関係は、通常の依存関係と同じようにtool.uv.sourcesにエントリを持つことができます。
開発依存関係を追加するには、--devフラグを含めます。:
PEP 508#
PEP 508では、依存性を指定するための構文を定義しています。この構文は、次の順序で構成されています。
- 依存関係の名前
- 必要な追加機能(オプション)
- バージョン指定子
- 環境マーカー(オプション)
バージョン指定子はカンマで区切られ、追加されます。例えばfoo >= 1.2.3, <2, !=1.4.0は"少なくとも1.2.3で、2より小さく、1.4.0ではないfooのバージョン"と解釈されます。
指定子は必要に応じて末尾にゼロが埋め込まれるので、foo ==2はfoo 2.0.0にも一致します。
例えばfoo ==2.1.*は2.1シリーズの任意のリリースを受け入れます。同様に、~=は最後の桁が等しいかそれより大きい場合に一致します。例えばfoo ~=1.2はfoo >=1.2,<2と等しく、foo ~=1.2.3はfoo >=1.2.3,<1.3と等しくなります。
エクストラは、名前とバージョンの間で角括弧で区切られます。たとえば、pandas[excel,plot] ==2.2のようになります。エクストラ名の間の空白は無視されます。
特定のPythonバージョンやオペレーティングシステムなど、特定の環境でのみ必要とされる依存関係もあります。例えば、importlib.metadataモジュールのimportlib-metadataバックポートをインストールするには、importlib-metadata >=7.1.0,<8;python_version < '3.10'を使用します。coloramaをWindowsにインストールするには(ただし、他のプラットフォームでは省略します)、colorama >=0.4.6,<5;platform_system == "Windows"を使用します。
マーカーはand、or、および括弧で結合されます。例えば、aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'。マーカー内のバージョンは引用符で囲む必要があり、マーカー外のバージョンは引用符で囲む必要がないことに注意してください。
Editable dependencies#
Pythonパッケージを含むディレクトリの通常のインストールでは、最初にホイールが構築され、次にそのホイールが仮想環境にインストールされて、すべてのソースファイルがコピーされます。パッケージのソースファイルが編集されると、仮想環境に古いバージョンが含まれます。
編集可能なインストールでは、仮想環境内のプロジェクトへのリンク(.pthファイル)を追加して、インタプリタにソースファイルを直接含めるように指示することで、この問題を解決します。
編集可能なものにはいくつかの制限がありますが(主に:ビルドバックエンドがそれらをサポートする必要があり、ネイティブモジュールはインポート前に再コンパイルされません)、仮想環境は常にパッケージの最新の変更を使用するので、開発に役立ちます。
uvは、デフォルトでワークスペースパッケージに対して編集可能なインストールを使用します。
編集可能な依存関係を追加するには、--editableフラグを使用します。:
または、ワークスペースでの編集可能な依存関係の使用をオプトアウトするには、次の手順に従います。: