uvを使った自己完結型 Python スクリプトの作成

• Python スクリプトで uv を活用し、依存関係の事前インストールなしですぐ実行できる自己完結型スクリプトを作る方法
• Go プロジェクトで API テスト用に Python スクリプトを使う場面から生まれた実用的なアプローチ

従来方式の限界

• httpx、IPython、loguru などのパッケージを使う Python スクリプトを実行するには、次のいずれかを選ぶ必要があった
  • システム Python に直接パッケージをインストールする
  • 仮想環境を作成し、パッケージをインストールしてから実行する
• どちらの方法も煩雑で、システム環境に影響を与える可能性があり、他人に共有する際の説明も長くなりがちだった

uv による手軽なスクリプト実行

• uv は Python パッケージマネージャー兼 pip 代替ツールで、隔離された実行環境で Python スクリプトを実行できる
• # /// script コメントにより、スクリプト内に依存関係の情報を明記できる

  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  

• この設定を含むスクリプトは、次のコマンドで実行できる

  uv run jam_users.py  
  

• uv は一時的な仮想環境の作成、必要なパッケージのインストール、スクリプトの実行までを自動でまとめて処理する

実行可能スクリプトにする

• 通常の Python スクリプトのように #!/usr/bin/env python を使って実行可能にすることもできるが、この方法では uv の script コメントを認識できない
• 代わりに、以下のように shebang に uv コマンドを直接書くことで解決できる

  #!/usr/bin/env -S uv run --script  
  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  

• この方法なら chmod +x 後に直接実行でき、ほかの Unix 系システムでも uv さえあればそのまま動作する

  ./jam_users.py  
  

利点と活用度

• uv 方式は、他の人にスクリプトを渡すときに非常に便利
• 複雑な事前設定なしでも、必要なパッケージと環境が自動でセットアップされる
• システム Python やグローバル環境を汚染しない
• スクリプト 1 本で実行と依存関係管理の両方を解決できる

筆者は、以前は他の人に Python スクリプトを渡す際にインストール手順の説明が複雑になっていたが、今では uv によってこの問題を簡単に解決できると説明している

• 小さなテスト用スクリプトだけでなく、実務向けの自動化スクリプトでも効果的