Skip to content

Configuring projectsプロジェクトの設定

Python version requirementPythonバージョンの要件

Projects may declare the Python versions supported by the project in the project.requires-python field of the pyproject.toml.プロジェクトは、project.requires-pythonフィールドの中で、プロジェクトがサポートするPythonのバージョンを宣言できます。

It is recommended to set a requires-python value:requires-pythonの値を設定することを推奨します：

pyproject.toml
[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.12"

The Python version requirement determines the Python syntax that is allowed in the project and affects selection of dependency versions (they must support the same Python version range).Pythonのバージョン要件は、プロジェクトで許可されるPythonの構文を決定し、依存関係のバージョンの選択に影響を与えます（それらは同じPythonバージョン範囲をサポートする必要があります）。

Entry pointsエントリーポイント

Entry points are the official term for an installed package to advertise interfaces. These include:エントリーポイントは、インストールされたパッケージがインターフェースを宣伝するための公式な用語です。これには以下が含まれます：

Important重要

Using the entry point tables requires a build system to be defined.エントリーポイントテーブルを使用するには、ビルドシステムを定義する必要があります。

Command-line interfacesコマンドラインインターフェース

Projects may define command line interfaces (CLIs) for the project in the [project.scripts] table of the pyproject.toml.プロジェクトは、pyproject.tomlの[project.scripts]テーブルでプロジェクトのコマンドラインインターフェース（CLI）を定義できます。

For example, to declare a command called hello that invokes the hello function in the example module:例えば、exampleモジュール内のhello関数を呼び出すhelloというコマンドを宣言するには:

pyproject.toml
[project.scripts]
hello = "example:hello"

Then, the command can be run from a console:その後、コマンドはコンソールから実行できます:

$ uv run hello

Graphical user interfacesグラフィカルユーザーインターフェース

Projects may define graphical user interfaces (GUIs) for the project in the [project.gui-scripts] table of the pyproject.toml.プロジェクトは、pyproject.tomlの[project.gui-scripts]テーブルでプロジェクトのグラフィカルユーザーインターフェース（GUI）を定義できます。

Important重要

These are only different from command-line interfaces on Windows, where they are wrapped by a GUI executable so they can be started without a console. On other platforms, they behave the same.これらは、Windowsではcommand-line interfacesとは異なり、GUI実行可能ファイルによってラップされているため、コンソールなしで起動できます。他のプラットフォームでは、同じように動作します。

For example, to declare a command called hello that invokes the app function in the example module:例えば、exampleモジュール内のapp関数を呼び出すhelloというコマンドを宣言するには:

pyproject.toml
[project.gui-scripts]
hello = "example:app"

Plugin entry pointsプラグインエントリポイント

Projects may define entry points for plugin discovery in the [project.entry-points] table of the pyproject.toml.プロジェクトは、pyproject.tomlの[project.entry-points]テーブルでプラグイン発見のためのエントリポイントを定義できます。

For example, to register the example-plugin-a package as a plugin for example:例えば、exampleのプラグインとしてexample-plugin-aパッケージを登録するには:

pyproject.toml
[project.entry-points.'example.plugins']
a = "example_plugin_a"

Then, in example, plugins would be loaded with:次に、exampleでは、プラグインが次のように読み込まれます：

example/__init__.py
from importlib.metadata import entry_points

for plugin in entry_points(group='example.plugins'):
    plugin.load()

Note注意

The group key can be an arbitrary value, it does not need to include the package name or "plugins". However, it is recommended to namespace the key by the package name to avoid collisions with other packages.このgroupキーは任意の値にすることができ、パッケージ名や「plugins」を含める必要はありません。ただし、他のパッケージとの衝突を避けるために、パッケージ名でキーを名前空間化することを推奨します。

Build systemsビルドシステム

A build system determines how the project should be packaged and installed. Projects may declare and configure a build system in the [build-system] table of the pyproject.toml.ビルドシステムは、プロジェクトがどのようにパッケージ化され、インストールされるべきかを決定します。プロジェクトは、[build-system]テーブルの中でビルドシステムを宣言し、設定することができます。

uv uses the presence of a build system to determine if a project contains a package that should be installed in the project virtual environment. If a build system is not defined, uv will not attempt to build or install the project itself, just its dependencies. If a build system is defined, uv will build and install the project into the project environment.uvは、ビルドシステムの存在を使用して、プロジェクトがプロジェクトの仮想環境にインストールされるべきパッケージを含んでいるかどうかを判断します。ビルドシステムが定義されていない場合、uvはプロジェクト自体をビルドまたはインストールしようとはせず、その依存関係のみを処理します。ビルドシステムが定義されている場合、uvはプロジェクトをプロジェクト環境にビルドしてインストールします。

The --build-backend option can be provided to uv init to create a packaged project with an appropriate layout. The --package option can be provided to uv init to create a packaged project with the default build system.--build-backendオプションをuv initに提供することで、適切なレイアウトのパッケージ化されたプロジェクトを作成できます。--packageオプションをuv initに提供することで、デフォルトのビルドシステムを使用したパッケージ化されたプロジェクトを作成できます。

Note注意

While uv will not build and install the current project without a build system definition, the presence of a [build-system] table is not required in other packages. For legacy reasons, if a build system is not defined, then setuptools.build_meta:__legacy__ is used to build the package. Packages you depend on may not explicitly declare their build system but are still installable. Similarly, if you add a dependency on a local project or install it with uv pip, uv will attempt to build and install it regardless of the presence of a [build-system] table.uvはビルドシステムの定義がない場合、現在のプロジェクトをビルドおよびインストールしませんが、他のパッケージに[build-system]テーブルが存在することは必須ではありません。レガシーの理由から、ビルドシステムが定義されていない場合、setuptools.build_meta:__legacy__がパッケージのビルドに使用されます。依存しているパッケージは、明示的にビルドシステムを宣言していない場合でも、インストール可能です。同様に、ローカルプロジェクトへの依存関係を追加したり、uv pipでインストールした場合、uvは[build-system]テーブルの存在に関係なく、それをビルドしてインストールしようとします。

Build systems are used to power the following features:ビルドシステムは、次の機能を支えるために使用されます：

  • Including or excluding files from distributions配布からファイルを含めたり除外したりすること
  • Editable installation behavior編集可能インストールの動作
  • Dynamic project metadata動的プロジェクトメタデータ
  • Compilation of native codeネイティブコードのコンパイル
  • Vendoring shared libraries共有ライブラリのベンダリング

To configure these features, refer to the documentation of your chosen build system.これらの機能を構成するには、選択したビルドシステムのドキュメントを参照してください。

Project packagingプロジェクトのパッケージング

As discussed in build systems, a Python project must be built to be installed. This process is generally referred to as "packaging".ビルドシステムで説明したように、Pythonプロジェクトはインストールされるためにビルドされる必要があります。このプロセスは一般的に「パッケージング」と呼ばれます。

You probably need a package if you want to:あなたがパッケージを必要とする可能性があるのは、次のような場合です：

  • Add commands to the projectプロジェクトにコマンドを追加する
  • Distribute the project to othersプロジェクトを他の人に配布する
  • Use a src and test layoutsrcおよびtestレイアウトを使用する
  • Write a libraryライブラリを書く

You probably do not need a package if you are:あなたはおそらく、次のような場合にはパッケージは必要ありません：

  • Writing scriptsスクリプトを書く
  • Building a simple applicationシンプルなアプリケーションを構築する
  • Using a flat layoutフラットなレイアウトを使用する

While uv usually uses the declaration of a build system to determine if a project should be packaged, uv also allows overriding this behavior with the tool.uv.package setting.uvは通常、プロジェクトがパッケージ化されるべきかどうかを判断するためにビルドシステムの宣言を使用しますが、uvはこの動作をtool.uv.package設定でオーバーライドすることも許可します。

Setting tool.uv.package = true will force a project to be built and installed into the project environment. If no build system is defined, uv will use the setuptools legacy backend.tool.uv.package = trueを設定すると、プロジェクトはビルドされ、プロジェクト環境にインストールされます。ビルドシステムが定義されていない場合、uvはsetuptoolsのレガシーバックエンドを使用します。

Setting tool.uv.package = false will force a project package not to be built and installed into the project environment. uv will ignore a declared build system when interacting with the project; however, uv will still respect explicit attempts to build the project such as invoking uv build.tool.uv.package = falseを設定すると、プロジェクトパッケージはビルドされず、プロジェクト環境にインストールされません。uvはプロジェクトと対話する際に宣言されたビルドシステムを無視しますが、uv buildを呼び出すなど、プロジェクトをビルドしようとする明示的な試みは尊重されます。

Project environment pathプロジェクト環境パス

The UV_PROJECT_ENVIRONMENT environment variable can be used to configure the project virtual environment path (.venv by default).UV_PROJECT_ENVIRONMENT環境変数は、プロジェクトの仮想環境パス（デフォルトでは.venv）を設定するために使用できます。

If a relative path is provided, it will be resolved relative to the workspace root. If an absolute path is provided, it will be used as-is, i.e., a child directory will not be created for the environment. If an environment is not present at the provided path, uv will create it.相対パスが提供された場合、それはワークスペースのルートに対して解決されます。絶対パスが提供された場合、それはそのまま使用され、すなわち環境のために子ディレクトリは作成されません。提供されたパスに環境が存在しない場合、uvはそれを作成します。

This option can be used to write to the system Python environment, though it is not recommended. uv sync will remove extraneous packages from the environment by default and, as such, may leave the system in a broken state.このオプションはシステムのPython環境に書き込むために使用できますが、推奨されません。uv syncはデフォルトで環境から余分なパッケージを削除し、そのためシステムが壊れた状態になる可能性があります。

To target the system environment, set UV_PROJECT_ENVIRONMENT to the prefix of the Python installation. For example, on Debian-based systems, this is usually /usr/local:システム環境をターゲットにするには、UV_PROJECT_ENVIRONMENTをPythonインストールのプレフィックスに設定します。例えば、Debianベースのシステムでは、通常は/usr/localです：

$ python -c "import sysconfig; print(sysconfig.get_config_var('prefix'))"
/usr/local

To target this environment, you'd export UV_PROJECT_ENVIRONMENT=/usr/local.この環境をターゲットにするには、UV_PROJECT_ENVIRONMENT=/usr/localをエクスポートします。

Important重要

If an absolute path is provided and the setting is used across multiple projects, the environment will be overwritten by invocations in each project. This setting is only recommended for use for a single project in CI or Docker images.絶対パスが提供され、設定が複数のプロジェクトで使用される場合、環境は各プロジェクトでの呼び出しによって上書きされます。この設定はCIやDockerイメージで単一のプロジェクトに対してのみ使用することが推奨されます。

Note注意

By default, uv does not read the VIRTUAL_ENV environment variable during project operations. A warning will be displayed if VIRTUAL_ENV is set to a different path than the project's environment. The --active flag can be used to opt-in to respecting VIRTUAL_ENV. The --no-active flag can be used to silence the warning.デフォルトでは、uvはプロジェクト操作中にVIRTUAL_ENV環境変数を読み込みません。VIRTUAL_ENVがプロジェクトの環境とは異なるパスに設定されている場合、警告が表示されます。--activeフラグを使用すると、VIRTUAL_ENVを尊重することができます。--no-activeフラグを使用すると、警告を抑制できます。

Build isolationビルドの隔離

By default, uv builds all packages in isolated virtual environments alongside their declared build dependencies, as per PEP 517.デフォルトでは、uvはすべてのパッケージを宣言されたビルド依存関係とともに隔離された仮想環境でビルドします。これはPEP 517に従っています。

Some packages are incompatible with this approach to build isolation, be it intentionally or unintentionally.一部のパッケージは、このビルドの隔離アプローチと互換性がありません。意図的または意図しない場合があります。

For example, packages like flash-attn and deepspeed need to build against the same version of PyTorch that is installed in the project environment; by building them in an isolated environment, they may inadvertently build against a different version of PyTorch, leading to runtime errors.例えば、flash-attnやdeepspeedのようなパッケージは、プロジェクト環境にインストールされているのと同じバージョンのPyTorchに対してビルドする必要があります。隔離された環境でそれらをビルドすると、異なるバージョンのPyTorchに対してビルドされてしまい、ランタイムエラーを引き起こす可能性があります。

In other cases, packages may accidentally omit necessary dependencies in their declared build dependency list. For example, cchardet requires cython to be installed in the project environment prior to installing cchardet, but does not declare it as a build dependency.他のケースでは、パッケージが宣言されたビルド依存関係リストから必要な依存関係を誤って省略することがあります。例えば、cchardetは、cchardetをインストールする前にプロジェクト環境にcythonがインストールされている必要がありますが、それをビルド依存関係として宣言していません。

To address these issues, uv supports two separate approaches to modifying the build isolation behavior:これらの問題に対処するために、uvはビルドアイソレーションの動作を変更するための2つの別々のアプローチをサポートしています：

  1. Augmenting the list of build dependencies: This allows you to install a package in an isolated environment, but with additional build dependencies that are not declared by the package itself via the extra-build-dependencies setting. For packages like flash-attn, you can even enforce that those build dependencies (like torch) match the version of the package that is or will be installed in the project environment.ビルド依存関係のリストを増強する：これにより、パッケージ自体がextra-build-dependencies設定を通じて宣言していない追加のビルド依存関係を持つ孤立した環境でパッケージをインストールできます。flash-attnのようなパッケージの場合、これらのビルド依存関係（例えばtorch）がプロジェクト環境にインストールされるパッケージのバージョンと一致することを強制することもできます。

  2. Disabling build isolation for specific packages: This allows you to install a package without building it in an isolated environment.特定のパッケージのビルドアイソレーションを無効にする：これにより、孤立した環境でビルドせずにパッケージをインストールできます。

When possible, we recommend augmenting the build dependencies rather than disabling build isolation entirely, as the latter approach requires that the build dependencies are installed in the project environment prior to installing the package itself, which can lead to more complex installation steps, the inclusion of extraneous packages in the project environment, and difficulty in reproducing the project environment in other contexts.可能な場合は、ビルドアイソレーションを完全に無効にするのではなく、ビルド依存関係を増強することをお勧めします。後者のアプローチでは、パッケージ自体をインストールする前にビルド依存関係がプロジェクト環境にインストールされている必要があり、これによりより複雑なインストール手順、プロジェクト環境に余分なパッケージが含まれること、他のコンテキストでプロジェクト環境を再現するのが難しくなる可能性があります。

Augmenting build dependenciesビルド依存関係の増強

To augment the list of build dependencies for a specific package, add it to the extra-build-dependencies list in your pyproject.toml.特定のパッケージのビルド依存関係のリストを増強するには、pyproject.tomlのextra-build-dependenciesリストに追加します。

For example, to build cchardet with cython as an additional build dependency, include the following in your pyproject.toml:例えば、cchardetを追加のビルド依存関係としてcythonを使用してビルドするには、pyproject.tomlに以下を含めます：

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["cchardet"]

[tool.uv.extra-build-dependencies]
cchardet = ["cython"]

To ensure that a build dependency matches the version of the package that is or will be installed in the project environment, set match-runtime = true in the extra-build-dependencies table. For example, to build deepspeed with torch as an additional build dependency, include the following in your pyproject.toml:ビルド依存関係がプロジェクト環境にインストールされるパッケージのバージョンと一致することを確認するには、extra-build-dependenciesテーブルにmatch-runtime = trueを設定します。例えば、deepspeedを追加のビルド依存関係としてtorchを使用してビルドするには、pyproject.tomlに以下を含めます：

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["deepspeed", "torch"]

[tool.uv.extra-build-dependencies]
deepspeed = [{ requirement = "torch", match-runtime = true }]

This will ensure that deepspeed is built with the same version of torch that is installed in the project environment.これにより、deepspeedはプロジェクト環境にインストールされているtorchの同じバージョンでビルドされることが保証されます。

Similarly, to build flash-attn with torch as an additional build dependency, include the following in your pyproject.toml:同様に、flash-attnを追加のビルド依存関係としてtorchを使用してビルドするには、次の内容をpyproject.tomlに含めてください。

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["flash-attn", "torch"]

[tool.uv.extra-build-dependencies]
flash-attn = [{ requirement = "torch", match-runtime = true }]

[tool.uv.extra-build-variables]
flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }

Note注意

The FLASH_ATTENTION_SKIP_CUDA_BUILD environment variable ensures that flash-attn is installed from a compatible, pre-built wheel, rather than attempting to build it from source, which requires access to the CUDA development toolkit. If the CUDA toolkit is not available, the environment variable can be omitted, and flash-attn will be installed from a pre-built wheel if one is available for the current platform, Python version, and PyTorch version.FLASH_ATTENTION_SKIP_CUDA_BUILD環境変数は、flash-attnがソースからビルドされるのではなく、互換性のある事前ビルドのホイールからインストールされることを保証します。ソースからビルドするにはCUDA開発ツールキットへのアクセスが必要です。CUDAツールキットが利用できない場合、環境変数は省略でき、flash-attnは現在のプラットフォーム、Pythonバージョン、およびPyTorchバージョンに対して利用可能な場合、事前ビルドのホイールからインストールされます。

Similarly, deep_gemm follows the same pattern:同様に、deep_gemmも同じパターンに従います。

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["deep_gemm", "torch"]

[tool.uv.sources]
deep_gemm = { git = "https://github.com/deepseek-ai/DeepGEMM" }

[tool.uv.extra-build-dependencies]
deep_gemm = [{ requirement = "torch", match-runtime = true }]

The use of extra-build-dependencies and extra-build-variables are tracked in the uv cache, such that changes to these settings will trigger a reinstall and rebuild of the affected packages. For example, in the case of flash-attn, upgrading the version of torch used in your project would subsequently trigger a rebuild of flash-attn with the new version of torch.extra-build-dependenciesおよびextra-build-variablesの使用はuvキャッシュで追跡されるため、これらの設定の変更は影響を受けるパッケージの再インストールと再ビルドをトリガーします。例えば、flash-attnの場合、プロジェクトで使用するtorchのバージョンをアップグレードすると、その後新しいバージョンのtorchでflash-attnの再ビルドがトリガーされます。

Dynamic metadata動的メタデータ

The use of match-runtime = true is only available for packages like flash-attn that declare static metadata. If static metadata is unavailable, uv is required to build the package during the dependency resolution phase; as such, uv cannot determine the version of the build dependency that would ultimately be installed in the project environment.match-runtime = trueの使用は、静的メタデータを宣言するflash-attnのようなパッケージにのみ利用可能です。静的メタデータが利用できない場合、uvは依存関係解決フェーズ中にパッケージをビルドする必要があり、そのためuvはプロジェクト環境に最終的にインストールされるビルド依存関係のバージョンを特定できません。

In other words, if flash-attn did not declare static metadata, uv would not be able to determine the version of torch that would be installed in the project environment, since it would need to build flash-attn prior to resolving the torch version.言い換えれば、flash-attnが静的メタデータを宣言していなかった場合、uvはプロジェクト環境にインストールされるtorchのバージョンを特定できません。なぜなら、torchのバージョンを解決する前にflash-attnをビルドする必要があるからです。

As a concrete example, axolotl is a popular package that requires augmented build dependencies, but does not declare static metadata, as the package's dependencies vary based on the version of torch that is installed in the project environment. In this case, users should instead specify the exact version of torch that they intend to use in their project, and then augment the build dependencies with that version.具体的な例として、axolotlは、拡張ビルド依存関係を必要とする人気のパッケージですが、パッケージの依存関係はプロジェクト環境にインストールされているtorchのバージョンに基づいて変わるため、静的メタデータを宣言していません。この場合、ユーザーはプロジェクトで使用する予定のtorchの正確なバージョンを指定し、そのバージョンでビルド依存関係を拡張する必要があります。

For example, to build axolotl against torch==2.6.0, include the following in your pyproject.toml:例えば、torch==2.6.0に対してaxolotlをビルドするには、次の内容をpyproject.tomlに含めてください。

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["axolotl[deepspeed, flash-attn]", "torch==2.6.0"]

[tool.uv.extra-build-dependencies]
axolotl = ["torch==2.6.0"]
deepspeed = ["torch==2.6.0"]
flash-attn = ["torch==2.6.0"]

Similarly, older versions of flash-attn did not declare static metadata, and thus would not have supported match-runtime = true out of the box. Unlike axolotl, though, flash-attn did not vary its dependencies based on dynamic properties of the build environment. As such, users could instead provide the flash-attn metadata upfront via the dependency-metadata setting, thereby forgoing the need to build the package during the dependency resolution phase. For example, to provide the flash-attn metadata upfront:同様に、古いバージョンのflash-attnは静的メタデータを宣言していなかったため、デフォルトではmatch-runtime = trueをサポートしていませんでした。しかし、axolotlとは異なり、flash-attnはビルド環境の動的プロパティに基づいて依存関係を変化させませんでした。そのため、ユーザーはflash-attnのメタデータを事前に提供することで、依存関係解決フェーズ中にパッケージをビルドする必要を回避できます。例えば、flash-attnのメタデータを事前に提供するには：

pyproject.toml
[[tool.uv.dependency-metadata]]
name = "flash-attn"
version = "2.6.3"
requires-dist = ["torch", "einops"]

Tipヒント

To determine the package metadata for a package like flash-attn, navigate to the appropriate Git repository, or look it up on PyPI and download the package's source distribution. The package requirements can typically be found in the setup.py or setup.cfg file.flash-attnのようなパッケージのパッケージメタデータを決定するには、適切なGitリポジトリに移動するか、PyPIで調べてパッケージのソース配布をダウンロードします。パッケージの要件は通常、setup.pyまたはsetup.cfgファイルに見つけることができます。

(If the package includes a built distribution, you can unzip it to find the METADATA file; however, the presence of a built distribution would negate the need to provide the metadata upfront, since it would already be available to uv.)(パッケージにビルド済みの配布物が含まれている場合、METADATAファイルを見つけるために解凍できます。ただし、ビルド済みの配布物が存在する場合、メタデータを事前に提供する必要はなく、すでにuvに利用可能です。)

The version field in tool.uv.dependency-metadata is optional for registry-based dependencies (when omitted, uv will assume the metadata applies to all versions of the package), but required for direct URL dependencies (like Git dependencies).tool.uv.dependency-metadataのversionフィールドは、レジストリベースの依存関係に対してはオプションですが（省略した場合、uvはメタデータがパッケージのすべてのバージョンに適用されると仮定します）、直接URL依存関係（Git依存関係など）には必須です。

Disabling build isolationビルドアイソレーションの無効化

Installing packages without build isolation requires that the package's build dependencies are installed in the project environment prior to building the package itself.ビルドアイソレーションなしでパッケージをインストールするには、パッケージのビルド依存関係がパッケージ自体をビルドする前にプロジェクト環境にインストールされている必要があります。

For example, historically, to install cchardet without build isolation, you would first need to install the cython and setuptools packages in the project environment, followed by a separate invocation to install cchardet without build isolation:例えば、歴史的に、ビルドアイソレーションなしでcchardetをインストールするには、まずプロジェクト環境にcythonとsetuptoolsパッケージをインストールし、その後、ビルドアイソレーションなしでcchardetをインストールするための別の呼び出しを行う必要があります。

$ uv venv
$ uv pip install cython setuptools
$ uv pip install cchardet --no-build-isolation

uv simplifies this process by allowing you to specify packages that should not be built in isolation via the no-build-isolation-package setting in your pyproject.toml and the --no-build-isolation-package flag in the command line. Further, when a package is marked for disabling build isolation, uv will perform a two-phase install, first installing any packages that support build isolation, followed by those that do not. As a result, if a project's build dependencies are included as project dependencies, uv will automatically install them before installing the package that requires build isolation to be disabled.uvは、このプロセスを簡素化し、pyproject.tomlのno-build-isolation-package設定とコマンドラインの--no-build-isolation-packageフラグを使用して、アイソレーションなしでビルドすべきパッケージを指定できるようにします。さらに、パッケージがビルドアイソレーションを無効化するようにマークされている場合、uvは2段階のインストールを実行し、最初にビルドアイソレーションをサポートするパッケージをインストールし、その後にサポートしないパッケージをインストールします。その結果、プロジェクトのビルド依存関係がプロジェクト依存関係として含まれている場合、uvはビルドアイソレーションを無効にする必要があるパッケージをインストールする前に自動的にそれらをインストールします。

For example, to install cchardet without build isolation, include the following in your pyproject.toml:例えば、ビルドアイソレーションなしでcchardetをインストールするには、pyproject.tomlに以下を含めます：

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["cchardet", "cython", "setuptools"]

[tool.uv]
no-build-isolation-package = ["cchardet"]

When running uv sync, uv will first install cython and setuptools in the project environment, followed by cchardet (without build isolation):uv syncを実行すると、uvは最初にプロジェクト環境にcythonとsetuptoolsをインストールし、その後にcchardet（ビルドアイソレーションなし）をインストールします。

$ uv sync --extra build
 + cchardet==2.1.7
 + cython==3.1.3
 + setuptools==80.9.0

Similarly, to install flash-attn without build isolation, include the following in your pyproject.toml:同様に、ビルドアイソレーションなしでflash-attnをインストールするには、pyproject.tomlに以下を含めます：

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["flash-attn", "torch"]

[tool.uv]
no-build-isolation-package = ["flash-attn"]

When running uv sync, uv will first install torch in the project environment, followed by flash-attn (without build isolation). As torch is both a project dependency and a build dependency, the version of torch is guaranteed to be consistent between the build and runtime environments.uv syncを実行すると、uvは最初にプロジェクト環境にtorchをインストールし、その後にflash-attn（ビルドアイソレーションなし）をインストールします。torchはプロジェクト依存関係とビルド依存関係の両方であるため、torchのバージョンはビルド環境とランタイム環境の間で一貫性が保証されます。

A downside of the above approach is that it requires the build dependencies to be installed in the project environment, which is appropriate for flash-attn (which requires torch both at build-time and runtime), but not for cchardet (which only requires cython at build-time).上記のアプローチの欠点は、ビルド依存関係がプロジェクト環境にインストールされる必要があることです。これは、ビルド時とランタイムの両方で torch を必要とする flash-attn には適していますが、ビルド時にのみ cython を必要とする cchardet には適していません。

To avoid including build dependencies in the project environment, uv supports a two-step installation process that allows you to separate the build dependencies from the packages that require them.プロジェクト環境にビルド依存関係を含めないようにするために、uv はビルド依存関係をそれらを必要とするパッケージから分離する二段階のインストールプロセスをサポートしています。

For example, the build dependencies for cchardet can be isolated to an optional build group, as in:例えば、cchardet のビルド依存関係は、次のようにオプショナルな build グループに隔離できます。

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["cchardet"]

[project.optional-dependencies]
build = ["setuptools", "cython"]

[tool.uv]
no-build-isolation-package = ["cchardet"]

Given the above, a user would first sync with the build optional group, and then without it to remove the build dependencies:これを踏まえて、ユーザーはまず build オプショナルグループと同期し、その後それなしでビルド依存関係を削除します。

$ uv sync --extra build
 + cchardet==2.1.7
 + cython==3.1.3
 + setuptools==80.9.0
$ uv sync
 - cython==3.1.3
 - setuptools==80.9.0

Some packages, like cchardet, only require build dependencies for the installation phase of uv sync. Others require their build dependencies to be present even just to resolve the project's dependencies during the resolution phase.cchardet のような一部のパッケージは、uv sync の インストール フェーズのためにのみビルド依存関係を必要とします。他のパッケージは、解決 フェーズ中にプロジェクトの依存関係を解決するために、ビルド依存関係が存在する必要があります。

In such cases, the build dependencies can be installed prior to running any uv lock or uv sync commands, using the lower lower-level uv pip API. For example, given:そのような場合、ビルド依存関係は、uv lock または uv sync コマンドを実行する前に、より低レベルの uv pip API を使用してインストールできます。例えば、次のようにします。

pyproject.toml
[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["flash-attn"]

[tool.uv]
no-build-isolation-package = ["flash-attn"]

You could run the following sequence of commands to sync flash-attn:flash-attn を同期するために、次のコマンドのシーケンスを実行できます。

$ uv venv
$ uv pip install torch setuptools
$ uv sync

Alternatively, users can instead provide the flash-attn metadata upfront via the dependency-metadata setting, thereby forgoing the need to build the package during the dependency resolution phase. For example, to provide the flash-attn metadata upfront:また、ユーザーは flash-attn のメタデータを事前に提供することもでき、dependency-metadata 設定を使用することで、依存関係解決フェーズ中にパッケージをビルドする必要を回避できます。例えば、flash-attn のメタデータを事前に提供するには、次のようにします。

pyproject.toml
[[tool.uv.dependency-metadata]]
name = "flash-attn"
version = "2.6.3"
requires-dist = ["torch", "einops"]

Editable mode編集可能モード

By default, the project will be installed in editable mode, such that changes to the source code are immediately reflected in the environment. uv sync and uv run both accept a --no-editable flag, which instructs uv to install the project in non-editable mode. --no-editable is intended for deployment use-cases, such as building a Docker container, in which the project should be included in the deployed environment without a dependency on the originating source code.デフォルトでは、プロジェクトは編集可能モードでインストールされるため、ソースコードへの変更が環境に即座に反映されます。uv sync と uv run はどちらも --no-editable フラグを受け入れ、これにより uv にプロジェクトを非編集可能モードでインストールするよう指示します。--no-editable は、プロジェクトが元のソースコードに依存せずにデプロイされた環境に含まれるべきである Docker コンテナのビルドなど、デプロイメントのユースケースを意図しています。

Conflicting dependencies依存関係の競合

uv resolves all project dependencies together, including optional dependencies ("extras") and dependency groups. If dependencies declared in one section are not compatible with those in another section, uv will fail to resolve the requirements of the project with an error.uvは、オプションの依存関係（"extras"）や依存関係グループを含むすべてのプロジェクト依存関係を一緒に解決します。あるセクションで宣言された依存関係が別のセクションの依存関係と互換性がない場合、uvはプロジェクトの要件を解決できず、エラーが発生します。

uv supports explicit declaration of conflicting dependency groups. For example, to declare that the optional-dependency groups extra1 and extra2 are incompatible:uvは、競合する依存関係グループの明示的な宣言をサポートしています。たとえば、optional-dependencyグループextra1とextra2が互換性がないことを宣言するには:

pyproject.toml
[tool.uv]
conflicts = [
    [
      { extra = "extra1" },
      { extra = "extra2" },
    ],
]

Or, to declare the development dependency groups group1 and group2 incompatible:また、開発依存関係グループgroup1とgroup2が互換性がないことを宣言するには:

pyproject.toml
[tool.uv]
conflicts = [
    [
      { group = "group1" },
      { group = "group2" },
    ],
]

See the resolution documentation for more.詳細については、解決に関するドキュメントを参照してください。

Limited resolution environments制限された解決環境

If your project supports a more limited set of platforms or Python versions, you can constrain the set of solved platforms via the environments setting, which accepts a list of PEP 508 environment markers. For example, to constrain the lockfile to macOS and Linux, and exclude Windows:プロジェクトがより限られたプラットフォームまたはPythonバージョンをサポートしている場合、environments設定を介して解決されたプラットフォームのセットを制約できます。この設定はPEP 508環境マーカーのリストを受け入れます。たとえば、ロックファイルをmacOSとLinuxに制約し、Windowsを除外するには:

pyproject.toml
[tool.uv]
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
]

See the resolution documentation for more.詳細については、解決に関するドキュメントを参照してください。

Required environments必要な環境

If your project must support a specific platform or Python version, you can mark that platform as required via the required-environments setting. For example, to require that the project supports Intel macOS:プロジェクトが特定のプラットフォームまたはPythonバージョンを必ずサポートする必要がある場合、そのプラットフォームをrequired-environments設定を介して必須としてマークできます。たとえば、プロジェクトがIntel macOSをサポートすることを要求するには:

pyproject.toml
[tool.uv]
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]

The required-environments setting is only relevant for packages that do not publish a source distribution (like PyTorch), as such packages can only be installed on environments covered by the set of pre-built binary distributions (wheels) published by that package.required-environments 設定は、ソース配布を公開しないパッケージ（PyTorchのような）にのみ関連します。このようなパッケージは、そのパッケージによって公開された事前構築されたバイナリ配布（ホイール）のセットでカバーされる環境にのみインストールできます。

See the resolution documentation for more.解決に関するドキュメントを参照してください。