Working on projectsプロジェクトに取り組む

uv supports managing Python projects, which define their dependencies in a pyproject.toml file.uvは、依存関係をpyproject.tomlファイルで定義するPythonプロジェクトの管理をサポートします。

Creating a new project新しいプロジェクトの作成

You can create a new Python project using the uv init command:次の uv init コマンドを使用して、新しい Python プロジェクトを作成できます:

$ uv init hello-world
$ cd hello-world

Alternatively, you can initialize a project in the working directory:または、作業ディレクトリでプロジェクトを初期化することもできます:

$ mkdir hello-world
$ cd hello-world
$ uv init

uv will create the following files:uv は次のファイルを作成します:

├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

The main.py file contains a simple "Hello world" program. Try it out with uv run:main.py ファイルにはシンプルな "Hello world" プログラムが含まれています。 uv run で試してみてください:

$ uv run main.py
Hello from hello-world!

Project structureプロジェクト構造

A project consists of a few important parts that work together and allow uv to manage your project. In addition to the files created by uv init, uv will create a virtual environment and uv.lock file in the root of your project the first time you run a project command, i.e., uv run, uv sync, or uv lock.プロジェクトは、uv がプロジェクトを管理できるように連携して動作するいくつかの重要な部分で構成されています。 uv init によって作成されたファイルに加えて、uv はプロジェクトコマンドを初めて実行する際に、プロジェクトのルートに仮想環境と uv.lock ファイルを作成します。つまり、uv run、 uv sync、または uv lock です。

A complete listing would look like:完全なリストは次のようになります:

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

pyproject.tomlpyproject.toml

The pyproject.toml contains metadata about your project:pyproject.toml にはプロジェクトに関するメタデータが含まれています:

pyproject.toml

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

You'll use this file to specify dependencies, as well as details about the project such as its description or license. You can edit this file manually, or use commands like uv add and uv remove to manage your project from the terminal.このファイルを使用して、依存関係やプロジェクトの説明やライセンスなどの詳細を指定します。このファイルは手動で編集することもできますし、uv addやuv removeのようなコマンドを使用してターミナルからプロジェクトを管理することもできます。

Tipヒント

See the official pyproject.toml guide for more details on getting started with the pyproject.toml format.公式のpyproject.tomlガイドを参照して、pyproject.tomlフォーマットの使い始めについての詳細を確認してください。

You'll also use this file to specify uv configuration options in a [tool.uv] section.このファイルを使用して、uvの設定オプションを[tool.uv]セクションで指定します。

.python-version.python-version

The .python-version file contains the project's default Python version. This file tells uv which Python version to use when creating the project's virtual environment..python-versionファイルには、プロジェクトのデフォルトのPythonバージョンが含まれています。このファイルは、プロジェクトの仮想環境を作成する際にuvにどのPythonバージョンを使用するかを指示します。

.venv.venv

The .venv folder contains your project's virtual environment, a Python environment that is isolated from the rest of your system. This is where uv will install your project's dependencies..venvフォルダーには、システムの他の部分から隔離されたPython環境であるプロジェクトの仮想環境が含まれています。ここでuvはプロジェクトの依存関係をインストールします。

See the project environment documentation for more details.プロジェクト環境のドキュメントを参照して、詳細を確認してください。

uv.lockuv.lock

uv.lock is a cross-platform lockfile that contains exact information about your project's dependencies. 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.uv.lockは、プロジェクトの依存関係に関する正確な情報を含むクロスプラットフォームのロックファイルです。プロジェクトの広範な要件を指定するために使用されるpyproject.tomlとは異なり、ロックファイルにはプロジェクト環境にインストールされる正確に解決されたバージョンが含まれています。このファイルはバージョン管理にチェックインする必要があり、マシン間で一貫した再現可能なインストールを可能にします。

uv.lock is a human-readable TOML file but is managed by uv and should not be edited manually.uv.lock は人間が読みやすいTOMLファイルですが、uvによって管理されており、手動で編集するべきではありません。

See the lockfile documentation for more details.ロックファイルのドキュメントを参照して、詳細を確認してください。

Managing dependencies依存関係の管理

You can add dependencies to your pyproject.toml with the uv add command. This will also update the lockfile and project environment:pyproject.toml に依存関係を追加するには、uv add コマンドを使用します。これにより、ロックファイルとプロジェクト環境も更新されます：

$ uv add requests

You can also specify version constraints or alternative sources:バージョン制約や代替ソースを指定することもできます：

$ # Specify a version constraint
$ uv add 'requests==2.31.0'

$ # Add a git dependency
$ uv add git+https://github.com/psf/requests

If you're migrating from a requirements.txt file, you can use uv add with the -r flag to add all dependencies from the file:requirements.txt ファイルから移行する場合は、uv add を -r フラグと共に使用して、ファイルからすべての依存関係を追加できます：

$ # Add all dependencies from `requirements.txt`.
$ uv add -r requirements.txt -c constraints.txt

To remove a package, you can use uv remove:パッケージを削除するには、uv remove を使用できます：

$ uv remove requests

To upgrade a package, run uv lock with the --upgrade-package flag:パッケージをアップグレードするには、uv lock を --upgrade-package フラグと共に実行します：

$ uv lock --upgrade-package requests

The --upgrade-package flag will attempt to update the specified package to the latest compatible version, while keeping the rest of the lockfile intact.--upgrade-package フラグは、指定されたパッケージを最新の互換バージョンに更新しようとしますが、ロックファイルの他の部分はそのまま保持されます。

See the documentation on managing dependencies for more details.依存関係の管理に関するドキュメントを参照して、詳細を確認してください。

Viewing your versionバージョンの表示

The uv version command can be used to read your package's version.uv version コマンドを使用して、パッケージのバージョンを読み取ることができます。

To get the version of your package, run uv version:パッケージのバージョンを取得するには、uv version を実行します：

$ uv version
hello-world 0.7.0

To get the version without the package name, use the --short option:パッケージ名なしでバージョンを取得するには、--short オプションを使用します：

$ uv version --short
0.7.0

To get version information in a JSON format, use the --output-format json option:JSON形式でバージョン情報を取得するには、--output-format json オプションを使用します：

$ uv version --output-format json
{
    "package_name": "hello-world",
    "version": "0.7.0",
    "commit_info": null
}

See the publishing guide for details on updating your package version.パッケージのバージョンを更新する詳細については、公開ガイドを参照してください。

Running commandsコマンドの実行

uv run can be used to run arbitrary scripts or commands in your project environment.uv run を使用して、プロジェクト環境内で任意のスクリプトやコマンドを実行できます。

Prior to every uv run invocation, uv will verify that the lockfile is up-to-date with the pyproject.toml, and that the environment is up-to-date with the lockfile, keeping your project in-sync without the need for manual intervention. uv run guarantees that your command is run in a consistent, locked environment.uv runを呼び出す前に、uvはロックファイルがpyproject.tomlと最新であること、そして環境がロックファイルと最新であることを確認し、手動での介入なしにプロジェクトを同期させます。uv runは、コマンドが一貫したロックされた環境で実行されることを保証します。

For example, to use flask:例えば、flask を使用するには：

$ uv add flask
$ uv run -- flask run -p 3000

Or, to run a script:または、スクリプトを実行するには：

example.py

# Require a project dependency
import flask

print("hello world")

$ uv run example.py

Alternatively, you can use uv sync to manually update the environment then activate it before executing a command:あるいは、uv sync を使用して環境を手動で更新し、その後コマンドを実行する前にそれをアクティブにすることができます：

macOS and LinuxWindows

$ uv sync
$ source .venv/bin/activate
$ flask run -p 3000
$ python example.py

PS> uv sync
PS> .venv\Scripts\activate
PS> flask run -p 3000
PS> python example.py

Note注意

The virtual environment must be active to run scripts and commands in the project without uv run. Virtual environment activation differs per shell and platform.プロジェクト内でスクリプトやコマンドを uv run なしで実行するには、仮想環境をアクティブにする必要があります。仮想環境のアクティベーションは、シェルやプラットフォームによって異なります。

See the documentation on running commands and scripts in projects for more details.コマンドとスクリプトの実行に関するドキュメントを参照して、詳細を確認してください。

Building distributions配布物のビルド

uv build can be used to build source distributions and binary distributions (wheel) for your project.uv build を使用して、プロジェクトのソース配布物およびバイナリ配布物（ホイール）をビルドできます。

By default, uv build will build the project in the current directory, and place the built artifacts in a dist/ subdirectory:デフォルトでは、uv build は現在のディレクトリでプロジェクトをビルドし、ビルドされたアーティファクトを dist/ サブディレクトリに配置します：

$ uv build
$ ls dist/
hello-world-0.1.0-py3-none-any.whl
hello-world-0.1.0.tar.gz

See the documentation on building projects for more details.プロジェクトのビルドに関するドキュメントを参照して、詳細を確認してください。

Next steps次のステップ

To learn more about working on projects with uv, see the projects concept page and the command reference.uvを使用してプロジェクトに取り組む方法について詳しく知りたい場合は、プロジェクトの概念ページと、コマンドリファレンスを参照してください。

Or, read on to learn how to export a uv lockfile to different formats.または、uvロックファイルを異なる形式にエクスポートする方法を学ぶために読み進めてください。