uvとインラインメタデータを活用してPythonスクリプトをサクッと配布する方法

Pythonスクリプトの配布は意外と面倒です。依存ライブラリのインストールやPythonのバージョン違いなど、開発環境と実行環境の違いを解決するのは厄介です。

本記事ではパッケージ・プロジェクト管理ツールのuvを使い、Pythonスクリプトを以下の一貫したステップで実行する方法を紹介します。

			
			$ curl -LsSf https://astral.sh/uv/install.sh | sh # 初回だけ uv のインストール
$ source $HOME/.local/bin/env                     # インストール直後だけ実行
$ wget https://www.example.com/script.py          # スクリプトのダウンロード
$ chmod +x script.py                              # スクリプトに実行権限を付与
$ ./script.py                                     # スクリプトの実行。仮想環境を作って、Pythonランタイムと依存ライブラリをインストール
hello, world!

		

uv 経由でスクリプトを実行するだけで、スクリプト実行用の仮想環境が用意され、依存ライブラリだけでなく、Pythonランタイムそのものも一緒にインストールされます。

依存ライブラリをインストールするために pip コマンドを叩くといった作業は不要です。

実際のプログラム

GETリクエストするPythonスクリプトのサンプルです(公式ドキュメントを一部改変)。

			
			#!/usr/bin/env -S uv run --script
# /// script
# requires-python = "==3.13.*"
# dependencies = [
#     "httpx",
# ]
# ///
import httpx
print(httpx.get("https://example.com"))

		

標準ライブラリに無い httpx を使っています。

ポイントは3つです

1. スクリプトを1ファイルにまとめる

1つ目はスクリプトを1ファイルで作成することです。

1ファイルをダウンロードするだけで完結します。

2. スクリプトに実行権限を付与

2つ目は、スクリプトに実行権限を付与することです。

プログラムの引数を考えずに $ ./script.py とするだけでプログラムを実行できます。

スクリプトの1行目のshebangで

			
			#!/usr/bin/env -S uv run --script

		

というように記述することで、 $ ./script.py という呼び出しが以下のように展開され、 uv 経由でスクリプトが呼び出されます。

			
			$ uv run --script script.py

		

参考 https://docs.astral.sh/uv/guides/scripts/#using-a-shebang-to-create-an-executable-file

3. 難しいことは uv にやらせる

いざ Python スクリプトを実行しようにも、どのランタイムを利用するかや依存ライブラリをどうやってインストールするかなどを考える必要があります。

Pythonは依存するランタイム(Pythonのバージョン)やライブラリをスクリプト内にインラインで記述する仕様が、PEP 723 – Inline script metadata で策定され、Python Packaging Authority(PyPA) に引き継がれています。

uv はAstral社が開発している高速なPythonのためのパッケージ・プロジェクトマネージャーです。uv は PEP 723 に対応しており、メタデータをインラインで記述したスクリプトをuv経由で起動すると、 スクリプト専用の仮想環境を作成し、その中で依存ランタイム・ライブラリを解決してスクリプトを実行します。

			
			# /// script
# requires-python = "==3.13.*"
# dependencies = [
#     "httpx",
# ]
# ///

		

この例では、以下を宣言しています

• requires-python
  • Python 3.13 系を利用
• dependencies
  • httpx ライブラリに依存

スクリプトを少し改変して仮想環境を確認してみましょう。

			
			#!/usr/bin/env -S uv run --script
# /// script
# requires-python = "==3.13.*"
# dependencies = [
#     "httpx",
# ]
# ///
import sys
import httpx
print(sys.version)
print(sys.executable)
print(httpx.__path__)

		

スクリプトを実行すると、仮想環境($HOME/.cache/uv/environments-v2/script-97eecadf7f4c1a62)に、ランタイムとライブラリがインストールされているのが確認できます。

			
			$ ./script.py
3.13.7 (main, Sep 18 2025, 19:47:49) [Clang 20.1.4 ]
/home/ubuntu/.cache/uv/environments-v2/script-97eecadf7f4c1a62/bin/python
['/home/ubuntu/.cache/uv/environments-v2/script-97eecadf7f4c1a62/lib/python3.13/site-packages/httpx']

		

uvとインラインメタデータで、Pythonスクリプトの実行を手軽に

Pythonはランタイム・依存ライブラリといったメタデータをスクリプトにインラインで記述する仕様があります(PEP 723)。

この仕組みを利用し、 uv 経由でスクリプトを実行し、依存ライブラリだけでなくPythonランタイムそのものも実行環境にインストールする方法を紹介しました。

ポイントは3つです

1. スクリプトを1ファイルにまとめる
2. スクリプトに実行権限を付与
3. 難しいことは uv にやらせる

uv インストール後は以下の3ステップを実行するだけです

			
			$ wget https://www.example.com/script.py  # スクリプトのダウンロード
$ chmod +x script.py                      # スクリプトに実行権限を付与
$ ./script.py                             # スクリプトの実行 

		

uv とインラインメタデータを活用すれば、Pythonを意識させずに最低限の短いコマンドを打つだけでスクリプトを配布・実行できます。

参考リンク

• uv公式ドキュメント - Scripts
• PEP 723 - Inline script metadata
• PyPa - Inline script metadata