Skip to content

Working on projects#

uvは[project]メタデータテーブルを持つpyproject.tomlを使ってPythonプロジェクトを管理することができます。

Creating a new project#

uv initコマンドを使用して、新しいPythonプロジェクトを作成できます。

$ uv init hello-world
$ cd hello-world

また、作業ディレクトリ内のプロジェクトを初期化することもできます。:

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

これにより、次のディレクトリ構造が作成されます。:

.
├── pyproject.toml
├── README.md
└── src
    └── hello_world
        └── __init__.py

Working on an existing project#

プロジェクトにすでに標準のpyproject.tomlが含まれている場合は、すぐにuvを使い始めることができます。uv addやuv runのようなコマンドは、最初に使用されたときにlockfileとenvironmentを作成します。

別のPythonパッケージマネージャから移行する場合は、uvを使用する前にpyproject.tomlを手動で編集する必要があります。ほとんどのPythonパッケージマネージャは、開発依存関係などの共通機能をサポートするためにpyproject.toml標準を拡張しています。これらの拡張は各パッケージマネージャに固有のもので、uvの形式に変換する必要があります。詳細については、project dependenciesのドキュメントを参照してください。

Project structure#

プロジェクトは、連携して動作し、uvがプロジェクトを管理できるようにするいくつかの重要な部分で構成されています。uvは、uv initによって作成されたファイルとともに、プロジェクトコマンドを初めて実行したときに、プロジェクトのルートに仮想環境とuv.lockファイルを作成します。

pyproject.toml#

pyproject.tomlには、プロジェクトに関するメタデータが含まれています。:

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

[tool.uv]
dev-dependencies = []

ここでは、依存関係や、説明やライセンスなどのプロジェクトに関する詳細を指定します。このファイルを手動で編集したり、uv addやuv removeなどのコマンドを使用してCLIからプロジェクトを管理することができます。

Tip

pyproject.tomlフォーマットの詳細については、公式のpyproject.tomlguideを参照してください。

.venv#

.venvフォルダには、プロジェクトの仮想環境が含まれています。これは、システムの他の部分から分離されたPython環境です。uvはここにプロジェクトの依存関係をインストールします。

詳細については、project environmentのドキュメントを参照してください。

uv.lock#

uv.lockは、プロジェクトの依存関係に関する正確な情報を含むクロスプラットフォームのロックファイルです。プロジェクトの広範な要件を指定するために使用されるpyproject.tomlとは異なり、ロックファイルにはプロジェクト環境にインストールされている正確に解決されたバージョンが含まれています。このファイルはバージョン管理にチェックインする必要があります。これにより、マシン間で一貫性のある再現可能なインストールが可能になります。

uv.lockは人間が読めるTOMLファイルですが、uvによって管理されているので、手動で編集してはいけません。

詳細については、lockfileのマニュアルを参照してください。

Managing dependencies#

uv addコマンドを使用してpyproject.tomlに依存関係を追加できます。これにより、ロックファイルとプロジェクト環境も更新されます:

$ uv add requests

バージョン制約または代替ソースを指定することもできます。:

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

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

パッケージを削除するには、uv removeを使用します。:

$ uv remove requests

See the documentation on managing dependencies for more details.

のmanaging dependenciesに関するドキュメントを参照してください。

Running commands#

uv runを使用すると、プロジェクト環境で任意のスクリプトやコマンドを実行できます。

すべてのuv run呼び出しの前に、uvはロックファイルがpyproject.tomlで最新であること、および環境がロックファイルで最新であることを確認し、手動による介入を必要とせずにプロジェクトを同期させます。uv runは、コマンドが一貫性のあるロックされた環境で実行されることを保証します。

例えば、flaskを使用するには:

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

または、次の手順でスクリプトを実行します。

example.py
# Require a project dependency
import flask

print("hello world")

$ uv run example.py

または、uv syncを使用して環境を手動で更新し、その環境をアクティブ化してから

executing a command:

コマンドの実行:

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

Note

uv runを使用せずにプロジェクト内のスクリプトとコマンドを実行するには、仮想環境がアクティブである必要があります。仮想環境のアクティブ化は、シェルとプラットフォームによって異なります。

詳細については、プロジェクトのrunning commandsおよびrunning scriptsのドキュメントを参照してください。

Next steps#

uvを使用したプロジェクトでの作業の詳細については、Projects conceptページおよびcommand referenceを参照してください。

または、publish your project as a packageの方法をお読みください。