ebal5 uv Shebang Python Script
Pythonで単体スクリプトを作成する際に使用するスキル。
発火条件
- Pythonで単体スクリプト（単一ファイルで完結するツール）を作成するとき
- 発火させたくない場合はユーザーが明示的に伝える（例：「プロジェクトのvenv使うのでuv単体スクリプトにしないで」）
テンプレート
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""スクリプトの説明."""
import argparse
import sys
def main() -> int:
parser = argparse.ArgumentParser(description="スクリプトの説明")
parser.add_argument("arg", help="引数の説明")
args = parser.parse_args()
# メイン処理
return 0
if __name__ == "__main__":
sys.exit(main())
構成要素
シェバン
#!/usr/bin/env -S uv run --script
-S オプションで複数引数を渡す。これによりuvが依存関係を自動解決して実行する。
PEP 723 インラインメタデータ
# /// script
# requires-python = ">=3.11"
# dependencies = [
# "requests>=2.28",
# "rich",
# ]
# ///
- TOMLコメント形式で依存関係を宣言
requires-python: 最小Pythonバージョン（3.11以上推奨）dependencies: pipの要件指定形式で依存パッケージを列挙
エントリーポイント
def main() -> int:
# 処理
return 0 # 終了コード
if __name__ == "__main__":
sys.exit(main())
main()は終了コードを返す（成功: 0、失敗: 1）sys.exit()で終了コードを伝播
ベストプラクティス
エラー出力
print("Error: something went wrong", file=sys.stderr)
return 1
エラーメッセージは標準エラー出力へ。
引数処理
シンプルな場合は argparse、複雑なCLIは typer を依存に追加：
# dependencies = ["typer"]
型ヒント
Python 3.11+の型ヒント構文を使用：
def process(items: list[str]) -> dict[str, int]:
...
ファイル配置
shebang で直接実行させるため、配置後に実行ビットを立てて PATH の通った ディレクトリに置く：
chmod +x <name>
- 単発ツール:
~/.local/bin/<name>など、PATH 上の個人用 bin - プロジェクト付属: リポジトリの
scripts/<name>（PATH には載せず./scripts/<name>で実行）
dotfiles マネージャで配布する場合は、その規約に従って配置する
（例: chezmoi なら dot_scripts/executable_<name> が適用後に
~/.scripts/<name> になる）。