Skip to content

Running scripts#

Pythonスクリプトは、たとえばpython<script>.pyのように、スタンドアロンで実行するためのファイルです。uvを使用してスクリプトを実行すると、環境を手動で管理することなく、スクリプトの依存関係を確実に管理できます。

Note

.. If you are not familiar with Python environments: every Python installation has an environment that packages can be installed in. Typically, creating virtual environments is recommended to isolate packages required by each script. uv automatically manages virtual environments for you and prefers a declarative approach to dependencies.

Python環境に精通していない場合:すべてのPythonインストールには、パッケージをインストールできる環境があります。通常、virtual environmentsを作成して、各スクリプトに必要なパッケージを分離することをお勧めします。uvは自動的に仮想環境を管理し、依存関係に対してdeclarativeアプローチを優先します。

Running a script without dependencies#

スクリプトに依存関係がない場合は、uv runで実行できます。:

example.py
print("Hello world")

$ uv run example.py
Hello world

同様に、スクリプトが標準ライブラリ内のモジュールに依存している場合は、何もすることがありません。

example.py
import os

print(os.path.expanduser("~"))

$ uv run example.py
/Users/astral

スクリプトには引数を指定できます。:

example.py
import sys

print(" ".join(sys.argv[1:]))

$ uv run example.py test
test

$ uv run example.py hello world!
hello world!

uv runを_project_、つまりpyproject.tomlのあるディレクトリで使用すると、スクリプトを実行する前に現在のプロジェクトがインストールされることに注意してください。スクリプトがプロジェクトに依存していない場合は、--no-projectフラグを使用してこれをスキップしてください。

$ # Note, it is important that the flag comes _before_ the script
$ uv run --no-project example.py

プロジェクトでの作業の詳細については、projects guideを参照してください。

Running a script with dependencies#

スクリプトに他のパッケージが必要な場合は、スクリプトが実行される環境にインストールする必要があります。uvでは、手動で依存関係を管理する長期の仮想環境を使用するのではなく、これらの環境をオンデマンドで作成することが推奨されています。これには、スクリプトに必要な依存関係の明示的な宣言が必要です。一般的には、projectまたはinline metadataを使用して依存関係を宣言することが推奨されますが、uvでは呼び出しごとの依存関係の要求もサポートされています。

たとえば、次のスクリプトはrichを必要とします。

example.py
import time
from rich.progress import track

for i in track(range(20), description="For example:"):
    time.sleep(0.05)

依存関係を指定せずに実行すると、このスクリプトは失敗します。:

$ uv run --no-project example.py
Traceback (most recent call last):
  File "/Users/astral/example.py", line 2, in <module>
    from rich.progress import track
ModuleNotFoundError: No module named 'rich'

--withオプションを使用して依存関係を要求します。:

$ uv run --with rich example.py
For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01

特定のバージョンが必要な場合は、要求された依存関係に制約を追加できます。:

$ uv run --with 'rich>12,<13' example.py

--withオプションで繰り返すことで、複数の依存関係を要求できます。

uv runが_project_で使用される場合、これらの依存関係はプロジェクトの依存関係に_追加で_含まれることに注意してください。この動作をオプトアウトするには、--no-projectフラグを使用してください。

Declaring script dependencies#

Pythonは最近、inline script metadataの標準フォーマットを追加しました。

This allows the dependencies for a script to be declared in the script itself.

これにより、スクリプトの依存関係をスクリプト自体で宣言することができます。

インラインスクリプトメタデータを使用するには、スクリプトの先頭にscriptセクションを追加し、TOMLを使用して依存関係を宣言します。:

example.py
# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

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

uvは、スクリプトの実行に必要な依存関係を持つ環境を自動的に作成します。たとえば、次のようになります。:

$ uv run example.py
[
│   ('1', 'PEP Purpose and Guidelines'),
│   ('2', 'Procedure for Adding New Modules'),
│   ('3', 'Guidelines for Handling Bug Reports'),
│   ('4', 'Deprecation of Standard Modules'),
│   ('5', 'Guidelines for Language Evolution'),
│   ('6', 'Bug Fix Releases'),
│   ('7', 'Style Guide for C Code'),
│   ('8', 'Style Guide for Python Code'),
│   ('9', 'Sample Plaintext PEP Template'),
│   ('10', 'Voting Guidelines')
]

Important

インラインスクリプトメタデータを使用する場合、uv runがused in a_project_であっても、プロジェクトの依存関係は無視されます。--no-projectフラグは必要ありません。

uvはPythonのバージョン要件にも対応しています。:

example.py
# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///

# Use some syntax added in Python 3.12
type Point = tuple[float, float]
print(Point)

Note

dependenciesフィールドは、空の場合でも指定する必要があります。

uv runは必要なPythonバージョンを検索して使用します。Pythonバージョンがインストールされていない場合はダウンロードされます。詳細については、Python versionsのドキュメントを参照してください。

Using different Python versions#

uvを使用すると、スクリプトを呼び出すたびに任意のバージョンのPythonを要求できます。次に例を示します。:

example.py
import sys

print(".".join(map(str, sys.version_info[:3])))

$ # Use the default Python version, may differ on your machine
$ uv run example.py
3.12.1

$ # Use a specific Python version
$ uv run --python 3.10 example.py
3.10.13

Pythonバージョンのリクエストの詳細については、Python version requestのマニュアルを参照してください。

Next steps#

uv runの詳細については、command referenceを参照してください。

または、uvを使用したツールの実行とインストールの方法を引き続きお読みください。