[Python] pipx の Inline script metadata が便利すぎる件

Python スクリプトを実行するとき、次のような問題に直面したことはありませんか？

そんな悩みを解決してくれるのが pipx と、PEP 723 で標準化された Inline Script Metadata の組み合わせです。

使ってみるととても便利だったので記事にしました！

この記事では、pipx を使って Python スクリプトを細かいことを考えず簡単に実行する方法ご紹介します。

pipx とは？

pipx は、Python パッケージ（特に CLI ツール）を グローバルに仮想環境付きでインストール・実行 できるツールです。

pipx run スクリプト.py

のように、一時的にパッケージを実行できるのが特徴です。

Python スクリプトの先頭に、次のようなコメントを記述することで、スクリプトが必要とする依存パッケージを明示できる仕組みです。

# /// script
# dependencies = ["requests"]
# ///

これにより、次のようにスクリプトを直接 pipx で実行できます。

pipx run ./example.py

pipx はスクリプト内のメタデータを読み取り、必要なパッケージ（この例では requests）を一時的にインストールしてから実行してくれます。

この機能は、もともと pipx が独自に考案・実装したものでした。2023年5月にリリースされた pipx v1.2.0 では、次のような 独自形式 で依存関係を記述できるようになりました。

# /// script
# dependencies = ["requests"]
# ///

この形式は非常に便利で、コミュニティ内でも注目を集めましたが、Python 標準としての仕様ではありませんでした。

同年2023年9月、Python コミュニティでは「複数のツールで共有できるメタデータの標準」が求められ、PEP 723（Embedding pyproject.toml Metadata in Python Scripts） が提案されました。

PEP 723 では、次のような TOML形式のメタデータ をコメントブロックとして記述する方法が定義されました。

# /// pyproject
# [project]
# dependencies = ["requests"]
# ///

これは、pipx だけでなく、uv, rye, pdm などのツールでも活用できるような 汎用仕様 として設計されています。

pipx は、その後この PEP 723 の仕様にも対応するようになりました。つまり、現在の pipx は

どちらの形式でもスクリプト実行時の依存解決が可能です。

以下のような Python スクリプト hello.py を用意します。

# /// script
# dependencies = ["rich"]
# ///

from rich import print
print("[bold green]Hello from pipx with rich![/bold green]")

このファイルを保存したら、次のコマンドで即実行できます。

pipx run ./hello.py

依存関係の rich がインストールされていなくても、pipx が自動で一時的に仮想環境を用意し、必要なパッケージをインストールしてスクリプトを実行してくれます。

pipx の Inline Script Metadata 機能は、ちょっとしたスクリプトの配布・実行を格段に楽にしてくれる強力なツールです。

Python スクリプトの可搬性を高めたい、依存管理をスマートにしたい方は、ぜひ一度この機能を試してみてください。