Skip to content

Project structure and filesプロジェクトの構造とファイル

The pyproject.tomlpyproject.tomlの

Python project metadata is defined in a pyproject.toml file. uv requires this file to identify the root directory of a project.Pythonプロジェクトのメタデータは pyproject.tomlファイルで定義されています。uvはこのファイルを使用してプロジェクトのルートディレクトリを特定します。

Tipヒント

uv init can be used to create a new project. See Creating projects for details.uv initを使用して新しいプロジェクトを作成できます。詳細についてはプロジェクトの作成を参照してください。

A minimal project definition includes a name and version:最小限のプロジェクト定義には、名前とバージョンが含まれます：

pyproject.toml
[project]
name = "example"
version = "0.1.0"

Additional project metadata and configuration includes:追加のプロジェクトメタデータと設定には、以下が含まれます：

The project environmentプロジェクト環境

When working on a project with uv, uv will create a virtual environment as needed. While some uv commands will create a temporary environment (e.g., uv run --isolated), uv also manages a persistent environment with the project and its dependencies in a .venv directory next to the pyproject.toml. It is stored inside the project to make it easy for editors to find — they need the environment to give code completions and type hints. It is not recommended to include the .venv directory in version control; it is automatically excluded from git with an internal .gitignore file.プロジェクトで作業する際、uvは必要に応じて仮想環境を作成します。いくつかのuvコマンドは一時的な環境を作成します（例：uv run --isolated）。また、uvはプロジェクトとその依存関係を含む永続的な環境を.venvディレクトリに管理します。このディレクトリはpyproject.tomlの隣に保存され、エディタが見つけやすくなっています。エディタはコード補完や型ヒントを提供するために環境が必要です。.venvディレクトリをバージョン管理に含めることは推奨されません；内部の.gitignoreファイルによって自動的にgitから除外されます。

To run a command in the project environment, use uv run. Alternatively the project environment can be activated as normal for a virtual environment.プロジェクト環境でコマンドを実行するには、uv runを使用します。あるいは、仮想環境のようにプロジェクト環境を通常通りにアクティブ化することもできます。

When uv run is invoked, it will create the project environment if it does not exist yet or ensure it is up-to-date if it exists. The project environment can also be explicitly created with uv sync. See the locking and syncing documentation for details.uv runが呼び出されると、まだ存在しない場合はプロジェクト環境を作成し、存在する場合は最新の状態に保ちます。プロジェクト環境はuv syncを使用して明示的に作成することもできます。詳細については、ロックと同期のドキュメントを参照してください。

It is not recommended to modify the project environment manually, e.g., with uv pip install. For project dependencies, use uv add to add a package to the environment. For one-off requirements, use uvx or uv run --with.プロジェクト環境を手動で変更することは推奨されません。例えば、uv pip installを使用しないでください。プロジェクトの依存関係には、uv addを使用して環境にパッケージを追加します。一時的な要件には、uvxまたはuv run --withを使用してください。

Tipヒント

If you don't want uv to manage the project environment, set managed = false to disable automatic locking and syncing of the project. For example:uvにプロジェクト環境を管理させたくない場合は、managed = falseを設定して、自動ロックとプロジェクトの同期を無効にします。例えば：

pyproject.toml
[tool.uv]
managed = false

The lockfileロックファイル

uv creates a uv.lock file next to the pyproject.toml.uvはpyproject.tomlの隣にuv.lockファイルを作成します。

uv.lock is a universal or cross-platform lockfile that captures the packages that would be installed across all possible Python markers such as operating system, architecture, and Python version.uv.lockは、オペレーティングシステム、アーキテクチャ、Pythonバージョンなどのすべての可能なPythonマーカーにわたってインストールされるパッケージをキャプチャするユニバーサルまたはクロスプラットフォームロックファイルです。

Unlike the pyproject.toml, which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. This file should be checked into version control, allowing for consistent and reproducible installations across machines.pyproject.tomlはプロジェクトの広範な要件を指定するために使用されるのに対し、ロックファイルにはプロジェクト環境にインストールされる正確に解決されたバージョンが含まれています。このファイルはバージョン管理にチェックインされるべきであり、マシン間で一貫した再現可能なインストールを可能にします。

A lockfile ensures that developers working on the project are using a consistent set of package versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known.ロックファイルは、プロジェクトに取り組む開発者が一貫したパッケージバージョンのセットを使用していることを保証します。さらに、アプリケーションとしてプロジェクトをデプロイする際に、使用されるパッケージバージョンの正確なセットが知られていることを保証します。

The lockfile is automatically created and updated during uv invocations that use the project environment, i.e., uv sync and uv run. The lockfile may also be explicitly updated using uv lock.ロックファイルは、プロジェクト環境を使用するuvの呼び出し中に自動的に作成および更新されます。つまり、uv syncおよびuv runです。ロックファイルはuv lockを使用して明示的に更新することもできます。

uv.lock is a human-readable TOML file but is managed by uv and should not be edited manually. The uv.lock format is specific to uv and not usable by other tools.uv.lockは人間が読めるTOMLファイルですが、uvによって管理されており、手動で編集するべきではありません。uv.lockフォーマットはuv特有のものであり、他のツールでは使用できません。

Relationship to pylock.tomlpylock.tomlとの関係

In PEP 751, Python standardized a new resolution file format, pylock.toml.PEP 751では、Pythonが新しい解決ファイル形式pylock.tomlを標準化しました。

pylock.toml is a resolution output format intended to replace requirements.txt (e.g., in the context of uv pip compile, whereby a "locked" requirements.txt file is generated from a set of input requirements). pylock.toml is standardized and tool-agnostic, such that in the future, pylock.toml files generated by uv could be installed by other tools, and vice versa.pylock.tomlは、requirements.txtを置き換えることを目的とした解決出力形式です（例えば、uv pip compileの文脈において、入力要件のセットから「ロックされた」requirements.txtファイルが生成されます）。pylock.tomlは標準化されており、ツールに依存しないため、将来的には、uvによって生成されたpylock.tomlファイルが他のツールによってインストールされることも、その逆も可能です。

Some of uv's functionality cannot be expressed in the pylock.toml format; as such, uv will continue to use the uv.lock format within the project interface.uvの機能の一部はpylock.toml形式で表現できないため、uvはプロジェクトインターフェース内でuv.lock形式を引き続き使用します。

However, uv supports pylock.toml as an export target and in the uv pip CLI. For example:しかし、uvはpylock.tomlをエクスポートターゲットとして、またuv pip CLIでサポートしています。例えば：

  • To export a uv.lock to the pylock.toml format, run: uv export -o pylock.tomluv.lockをpylock.toml形式にエクスポートするには、次のコマンドを実行します：uv export -o pylock.toml
  • To generate a pylock.toml file from a set of requirements, run: uv pip compile requirements.in -o pylock.toml要件のセットからpylock.tomlファイルを生成するには、次のコマンドを実行します：uv pip compile requirements.in -o pylock.toml
  • To install from a pylock.toml file, run: uv pip sync pylock.toml or uv pip install -r pylock.tomlpylock.tomlファイルからインストールするには、次のコマンドを実行します：uv pip sync pylock.tomlまたはuv pip install -r pylock.toml