Locking and syncingロックと同期
Locking is the process of resolving your project's dependencies into a lockfile. Syncing is the process of installing a subset of packages from the lockfile into the project environment.ロックは、プロジェクトの依存関係をロックファイルに解決するプロセスです。同期は、ロックファイルからプロジェクト環境にパッケージのサブセットをインストールするプロセスです。
Automatic lock and sync自動ロックと同期
Locking and syncing are automatic in uv. For example, when uv run is used, the project is locked
and synced before invoking the requested command. This ensures the project environment is always
up-to-date. Similarly, commands which read the lockfile, such as uv tree, will automatically
update it before running.ロックと同期はuvでは自動です。例えば、uv runが使用されると、要求されたコマンドを呼び出す前にプロジェクトがロックされ、同期されます。これにより、プロジェクト環境が常に最新の状態に保たれます。同様に、uv treeのようにロックファイルを読み取るコマンドは、実行する前に自動的にロックファイルを更新します。
To disable automatic locking, use the --locked option:自動ロックを無効にするには、--lockedオプションを使用します:
If the lockfile is not up-to-date, uv will raise an error instead of updating the lockfile.ロックファイルが最新でない場合、uvはロックファイルを更新する代わりにエラーを発生させます。
To use the lockfile without checking if it is up-to-date, use the --frozen option:ロックファイルが最新であるかどうかを確認せずに使用するには、--frozenオプションを使用します:
Similarly, to run a command without checking if the environment is up-to-date, use the --no-sync
option:同様に、環境が最新であるかどうかを確認せずにコマンドを実行するには、--no-syncオプションを使用します:
Checking the lockfileロックファイルの確認
When considering if the lockfile is up-to-date, uv will check if it matches the project metadata.
For example, if you add a dependency to your pyproject.toml, the lockfile will be considered
outdated. Similarly, if you change the version constraints for a dependency such that the locked
version is excluded, the lockfile will be considered outdated. However, if you change the version
constraints such that the existing locked version is still included, the lockfile will still be
considered up-to-date.ロックファイルが最新であるかどうかを考慮する際、uvはそれがプロジェクトのメタデータと一致するかどうかを確認します。例えば、pyproject.tomlに依存関係を追加すると、ロックファイルは古くなったと見なされます。同様に、依存関係のバージョン制約を変更してロックされたバージョンが除外される場合、ロックファイルは古くなったと見なされます。ただし、既存のロックされたバージョンがまだ含まれるようにバージョン制約を変更した場合、ロックファイルは最新の状態と見なされます。
You can check if the lockfile is up-to-date by passing the --check flag to uv lock:ロックファイルが最新であるかどうかは、--checkフラグをuv lockに渡すことで確認できます。
This is equivalent to the --locked flag for other commands.これは他のコマンドの--lockedフラグと同等です。
Important重要
uv will not consider lockfiles outdated when new versions of packages are released — the lockfile needs to be explicitly updated if you want to upgrade dependencies. See the documentation on upgrading locked package versions for details.新しいバージョンのパッケージがリリースされても、uvはロックファイルを古くなったと見なさない — 依存関係をアップグレードしたい場合は、ロックファイルを明示的に更新する必要があります。詳細については、ロックされたパッケージバージョンのアップグレードに関するドキュメントを参照してください。
Creating the lockfileロックファイルの作成
While the lockfile is created automatically, the lockfile may also be
explicitly created or updated using uv lock:ロックファイルは自動的に作成されますが、uv lockを使用して明示的に作成または更新することもできます。
Syncing the environment環境の同期
While the environment is synced automatically, it may also be explicitly
synced using uv sync:環境は自動的に同期されますが、uv syncを使用して明示的に同期することもできます。
Syncing the environment manually is especially useful for ensuring your editor has the correct versions of dependencies.環境を手動で同期することは、エディタが依存関係の正しいバージョンを持っていることを確認するために特に便利です。
Editable installation編集可能なインストール
When the environment is synced, uv will install the project (and other workspace members) as editable packages, such that re-syncing is not necessary for changes to be reflected in the environment.環境が同期されると、uvはプロジェクト（および他のワークスペースメンバー）を編集可能なパッケージとしてインストールし、変更が環境に反映されるために再同期する必要がありません。
To opt-out of this behavior, use the --no-editable option.この動作を無効にするには、--no-editable オプションを使用してください。
Note注意
If the project does not define a build system, it will not be installed. See the build systems documentation for details.プロジェクトがビルドシステムを定義していない場合、インストールされません。 詳細については、ビルドシステムのドキュメントを参照してください。
Retaining extraneous packages余分なパッケージの保持
Syncing is "exact" by default, which means it will remove any packages that are not present in the lockfile.同期はデフォルトで「正確」であり、これはロックファイルに存在しないパッケージを削除することを意味します。
To retain extraneous packages, use the --inexact option:余分なパッケージを保持するには、--inexact オプションを使用してください：
Syncing optional dependenciesオプションの依存関係の同期
uv reads optional dependencies from the [project.optional-dependencies] table. These are
frequently referred to as "extras".uvは[project.optional-dependencies]テーブルからオプションの依存関係を読み取ります。これらはしばしば「エクストラ」と呼ばれます。
uv does not sync extras by default. Use the --extra option to include an extra.uvはデフォルトでエクストラを同期しません。エクストラを含めるには、--extra オプションを使用してください。
To quickly enable all extras, use the --all-extras option.すべてのエクストラを迅速に有効にするには、--all-extras オプションを使用してください。
See the optional dependencies documentation for details on how to manage optional dependencies.オプションの依存関係を管理する方法についての詳細は、オプションの依存関係のドキュメントを参照してください。
Syncing development dependencies開発依存関係の同期
uv reads development dependencies from the [dependency-groups] table (as defined in
PEP 735).uvは、[dependency-groups]テーブルから開発依存関係を読み取ります（PEP 735で定義されています）。
The dev group is special-cased and synced by default. See the
default groups documentation for details on changing the
defaults.devグループは特別扱いされ、デフォルトで同期されます。デフォルトを変更する詳細については、デフォルトグループのドキュメントを参照してください。
The --no-dev flag can be used to exclude the dev group.--no-devフラグを使用すると、devグループを除外できます。
The --only-dev flag can be used to install the dev group without the project and its
dependencies.--only-devフラグを使用すると、プロジェクトとその依存関係を除いて、devグループをインストールできます。
Additional groups can be included or excluded with the --all-groups, --no-default-groups,
--group <name>, --only-group <name>, and --no-group <name> options. The semantics of
--only-group are the same as --only-dev, the project will not be included. However,
--only-group will also exclude default groups.追加のグループは、--all-groups、--no-default-groups、--group <name>、--only-group <name>、および--no-group <name>オプションを使用して含めたり除外したりできます。--only-groupの意味は--only-devと同じで、プロジェクトは含まれません。ただし、--only-groupはデフォルトグループも除外します。
Group exclusions always take precedence over inclusions, so given the command:グループの除外は常に包含より優先されるため、次のコマンドを考えてみてください：
The foo group would not be installed.fooグループはインストールされません。
See the development dependencies documentation for details on how to manage development dependencies.開発依存関係のドキュメントを参照して、開発依存関係の管理方法についての詳細を確認してください。
Upgrading locked package versionsロックされたパッケージバージョンのアップグレード
With an existing uv.lock file, uv will prefer the previously locked versions of packages when
running uv sync and uv lock. Package versions will only change if the project's dependency
constraints exclude the previous, locked version.既存の uv.lock ファイルがある場合、uv は uv sync および uv lock を実行する際に、以前にロックされたパッケージのバージョンを優先します。パッケージのバージョンは、プロジェクトの依存関係の制約が以前のロックされたバージョンを除外しない限り変更されません。
To upgrade all packages:すべてのパッケージをアップグレードするには:
To upgrade a single package to the latest version, while retaining the locked versions of all other packages:他のすべてのパッケージのロックされたバージョンを保持しながら、単一のパッケージを最新バージョンにアップグレードするには:
To upgrade a single package to a specific version:単一のパッケージを特定のバージョンにアップグレードするには:
In all cases, upgrades are limited to the project's dependency constraints. For example, if the project defines an upper bound for a package then an upgrade will not go beyond that version.すべての場合において、アップグレードはプロジェクトの依存関係の制約に制限されます。たとえば、プロジェクトがパッケージの上限を定義している場合、アップグレードはそのバージョンを超えることはありません。
Note注意
uv applies similar logic to Git dependencies. For example, if a Git dependency references
the main branch, uv will prefer the locked commit SHA in an existing uv.lock file over
the latest commit on the main branch, unless the --upgrade or --upgrade-package flags
are used.uv は Git 依存関係にも同様のロジックを適用します。たとえば、Git 依存関係が main ブランチを参照している場合、uv は既存の uv.lock ファイル内のロックされたコミット SHA を main ブランチの最新のコミットよりも優先します。ただし、--upgrade または --upgrade-package フラグが使用されている場合は除きます。
These flags can also be provided to uv sync or uv run to update the lockfile and the
environment.これらのフラグは uv sync または uv run にも提供でき、ロックファイルを更新することができます かつ 環境を更新します。
Exporting the lockfileロックファイルのエクスポート
If you need to integrate uv with other tools or workflows, you can export uv.lock to different
formats including requirements.txt, pylock.toml (PEP 751), and CycloneDX SBOM.uv を他のツールやワークフローと統合する必要がある場合、uv.lock を requirements.txt、pylock.toml (PEP 751)、および CycloneDX SBOM などの異なる形式にエクスポートできます。
$ uv export --format requirements.txt
$ uv export --format pylock.toml
$ uv export --format cyclonedx1.5
See the export guide for comprehensive documentation on all export formats and their use cases.すべてのエクスポート形式とその使用例に関する包括的なドキュメントについては、エクスポートガイドを参照してください。
Partial installations部分インストール
Sometimes it's helpful to perform installations in multiple steps, e.g., for optimal layer caching
while building a Docker image. uv sync has several flags for this purpose.時には、最適なレイヤーキャッシングのために、Dockerイメージを構築する際に複数のステップでインストールを行うことが役立ちます。 uv sync にはこの目的のためのいくつかのフラグがあります。
--no-install-project: Do not install the current project--no-install-project: 現在のプロジェクトをインストールしない--no-install-workspace: Do not install any workspace members, including the root project--no-install-workspace: ルートプロジェクトを含むワークスペースメンバーをインストールしない--no-install-package <NO_INSTALL_PACKAGE>: Do not install the given package(s)--no-install-package <NO_INSTALL_PACKAGE>: 指定されたパッケージをインストールしない
When these options are used, all the dependencies of the target are still installed. For example,
--no-install-project will omit the project but not any of its dependencies.これらのオプションを使用すると、ターゲットのすべての依存関係はまだインストールされます。例えば、--no-install-project は プロジェクト を省略しますが、その依存関係は省略しません。
If used improperly, these flags can result in a broken environment since a package can be missing its dependencies.不適切に使用すると、これらのフラグは環境を壊す原因となる可能性があります。なぜなら、パッケージが依存関係を欠いている可能性があるからです。