Skip to content

Projects#

Pythonプロジェクトは、複数のファイルにまたがるPythonアプリケーションの管理に役立ちます。

Tip

uvを使用してプロジェクトを作成する方法については、まずprojects guideを参照してください。

Project metadata#

Pythonプロジェクトのメタデータはpyproject.tomlファイルで定義されています。

uv initを使用して、基本的なpyproject.tomlとパッケージ定義を持つ新しいプロジェクトを作成できます。

最小のプロジェクト定義には、名前、バージョン、および説明が含まれます。

pyproject.toml
[project]
name = "example"
version = "0.1.0"
description = "Add your description here"

さらに、Pythonのバージョン要件を含めることをお勧めします。:

pyproject.toml
[project]
requires-python = ">=3.12"

このPythonバージョン要件は、プロジェクトで有効な構文を決定し、使用可能な依存関係のバージョンに影響します(それらは同じPython範囲をサポートする必要があります)。

pyproject.tomlにはプロジェクトの依存関係もリストされます。uvは、コマンドラインからuv addとuv removeを使用して標準の依存関係リストを変更することをサポートしています。uvは上級ユーザーのためにextended package sourcesもサポートしています。

Tip

pyproject.tomlの詳細については、公式のpyproject.tomlguideを参照してください。

Project environments#

uvは、pyproject.tomlの隣の.venvディレクトリに仮想環境を作成します。この仮想環境には、プロジェクトとその依存関係が含まれています。この仮想環境は、エディタが簡単に見つけられるようにプロジェクト内に保存されます。エディタは、コード補完と型のヒントを与えるためにこの環境を必要とします。バージョン管理に.venvディレクトリを含めることはお勧めしません。内部.gitignoreファイルによってgitから自動的に除外されます。

uv runが呼び出されると、プロジェクト環境がまだ存在しない場合は作成され、存在する場合は最新の状態になります。プロジェクト環境はuv syncで明示的に作成することもできます。

プロジェクト環境でコマンドを実行するには、uv runを使用します。または、プロジェクト環境を通常の仮想環境としてアクティブにすることもできます。

例えばuv pip installのように、プロジェクト環境を手動で変更することは_お勧めできません_。プロジェクトの依存関係については、uv addを使用して環境にパッケージを追加します。単発の要件については、uvxまたはuv run --withを使用します。

Lockfile#

uvはpyproject.tomlの次にuv.lockファイルを作成します。

uv.lockは、オペレーティングシステム、アーキテクチャ、Pythonのバージョンなど、すべてのPythonマーカーにわたってインストールされるパッケージをキャプチャする_universal_lockfileです。

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

ロックファイルは、プロジェクトで作業している開発者が一貫したパッケージバージョンのセットを使用していることを保証します。さらに、プロジェクトをアプリケーションとして配備するときに、使用されているパッケージバージョンの正確なセットがわかっていることを保証しま

ロックファイルは、プロジェクト環境を使用するuv呼び出し(つまり、uv syncおよびuv run)中に作成および更新されます。ロックファイルは、uv lockを使用して明示的に更新することもできます。

uv.lockは人間が読めるTOMLファイルですが、uvによって管理されており、手動で編集すべきではありません。現時点ではロックファイルのPython標準はないので、このファイルのフォーマットはuvに固有のものであり、一般に他のツールでは使用できません。

uv syncおよびuv runの呼び出し中にロックファイルが更新されないようにするには、--frozenフラグを使用します。

ロックファイルが最新であることをアサートするには、--lockedフラグを使用します。ロックファイルが最新でない場合は、ロックファイルを更新せずにエラーが発生します。

Managing dependencies#

uvは、CLIを使用して依存関係を追加、更新、および削除できます。

依存関係を追加するには:

$ uv add httpx

uvは、editable dependencies、development dependencies、optional dependencies、およびalternativedependency sourcesの追加をサポートしています。詳細については、dependency specificationのマニュアルを参照してください。

依存性を解決できない場合、uvはエラーを発生させます。:

$ uv add 'httpx>9999'
error: Because only httpx<=9999 is available and example==0.1.0 depends on httpx>9999, we can conclude that example==0.1.0 cannot be used.
And because only example==0.1.0 is available and you require example, we can conclude that the requirements are unsatisfiable.

依存関係を削除するには:

$ uv remove httpx

既存の依存関係を更新するには、例えばhttpxバージョンに下限を追加するには:

$ uv add 'httpx>0.1.0'

または、httpxのバージョンを変更します:

$ uv add 'httpx<0.2.0'

開発中にGitHubからhttpxを使用するなど、依存関係のソースを追加するには:

$ uv add git+https://github.com/encode/httpx

Running commands#

プロジェクトで作業している場合、プロジェクトは.venvの仮想環境にインストールされます。この環境はデフォルトで現在のシェルから分離されているので、プロジェクトを必要とする呼び出し(例えばpython -c "import example")は失敗します。代わりにuv runを使ってプロジェクト環境でコマンドを実行してください:

$ uv run python -c "import example"

runを使用すると、uvは指定されたコマンドを実行する前にプロジェクト環境が最新であることを確認します。

指定されたコマンドは、プロジェクト環境によって提供されるか、またはその外部に存在します。たとえば:

$ # Presuming the project provides `example-cli`
$ uv run example-cli foo

$ # Running a `bash` script that requires the project to be available
$ uv run bash scripts/foo.sh

Running commands with additional dependencies#

呼び出しごとに、追加の依存関係または異なるバージョンの依存関係を要求できます。

--withオプションは、例えば異なるバージョンのhttpxを要求するなど、呼び出しの依存関係を含めるために使用されます。:

$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
0.26.0
$ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
0.25.0

if the project requires httpx==0.24.0, the output above would be the same.

要求されたバージョンは、プロジェクトの要件に関係なく尊重されます。たとえば、プロジェクトにhttpx==0.24.0が必要な場合でも、上記の出力は同じになります。

Running scripts#

インラインメタデータを宣言するスクリプトは、プロジェクトから分離された環境で自動的に実行されます。詳細については、scripts guideを参照してください。

たとえば、次のスクリプトがあるとします。:

example.py
# /// script
# dependencies = [
#   "httpx",
# ]
# ///

import httpx

resp = httpx.get("https://peps.python.org/api/peps.json")
data = resp.json()
print([(k, v["title"]) for k, v in data.items()][:10])

uv run example.pyを呼び出すと、指定された依存関係のみがリストされた状態でプロジェクトから_isolated_が実行されます。

Projects with many packages#

多数のパッケージで構成されるプロジェクトで作業する場合は、workspacesのドキュメントを参照してください。