この記事は uv のドキュメント にある、「単一ファイルスクリプトの依存関係管理機能」+「Git repository ソースの指定」を使用しただけの話ですが、実際に動作確認したメモです。動作確認した uv のバージョンは以下です。
$ uv --version
uv 0.8.3 (7e78f54e7 2025-07-24)
導入 (短縮版)
異なるプロジェクトの Python スクリプト間で関数を共有したいが、使用するプロジェクト側にパッケージ管理用のファイルまで置きたくないこともあると思います。そのようなときは、「スクリプト内メタデータ (PEP 723) での依存関係管理」+「GitHub リポジトリをソースに指定 (PEP 508)」に対応したパッケージ管理ツール (ここでは uv) を使うと便利です。
導入 (短縮しない版) (読み飛ばしてよいです)
非 Python プロジェクトで、ちょっとした自動化だけ Python スクリプトでやることがあると思います (Ex. Web サイトの目次ページ生成など)。そうしていると、やがて複数プロジェクトのスクリプトで共通の関数 (やクラス) を使用したくなることもあると思います。
共通の関数を切り出して PyPI に登録すればどこからでも使用できますが、関数の仕様が限定的で PyPI に登録するようなものではない場合もあると思います。
pip は GitHub 等のリポジトリからのインストールもサポートしているので [1]、GitHub リポジトリを作成して関数を置き、プロジェクトメンバーに pip install git+https://github.com/xxxxxx/my-utils.git@v1.0.0 などとインストールしてもらうことはできると思います。が、「Note: モジュール my_utils は PyPI パッケージではありません。github.com から以下のコマンドでインストールしてください...」と README なりスクリプト冒頭なりに記述する必要があります。これはメンバーに手間をかけさせるし、記述を見落として詰まるメンバーも出るだろうし、モジュールを @v1.1.0 に修正した暁には見落として詰まるメンバーがもっと出ると思います。これならもう Python パッケージ管理ツールを導入したほうがよいですが、非 Python プロジェクトに requirements.txt だか pyproject.toml だかの依存関係管理ファイルまで追加するとごちゃごちゃするという場合もあると思います。
そこで便利なのが、PEP 723 で定義されたスクリプト内にコメントでメタデータを埋め込む形式です [2]。Python パッケージ管理ツールのうち uv などはこのメタデータから依存パッケージをインストールすることに対応しています [3][4]。GitHub リポジトリからのインストールも可能です。なので、スクリプト内にリポジトリ URL とタグ (あるいはコミットハッシュ) を指定しておけば、設定ファイルを追加することなく、メンバーはいつも uv run script.py を実行するだけで指定のバージョンのモジュールを読み込むことができます。また、GitHub Actions などでもスクリプトを実行しやすくなると思います。
モジュール側
以下のモジュールの以下のコミットハッシュを読み込めるか確認します。
CookieBox26/cookies-site-utils at c99762d7fd94bcc380e7d1a8a5e424cc93e77eca
動作確認用なので以下の関数 hoge() しかありません。
def hoge():
print('Welcome to Cookie\'s Site Utils!!')
スクリプトから読み込む前に、そもそも以下でインストールできるか確認しておきます。
pip install git+https://github.com/CookieBox26/cookies-site-utils.git
モジュールをインポートするスクリプト側
以下のパターン1とパターン2のどちらのメタデータの書き方でも、GitHub 上のモジュールをインポートできます。
- パターン1は uv のドキュメント [5] にある Git repository 指定方法に倣ったものです。
- パターン2は PEP 508 の URL 直接指定形式です。横に長く読みにくい気がしますが、uv 非依存にできます (が uv 前提ならパターン1が読みやすい気がします)。
# /// script
# requires-python = "==3.11.*"
# dependencies = [
# "cookies_site_utils",
# ]
# [tool.uv.sources.cookies_site_utils]
# git = "https://github.com/CookieBox26/cookies-site-utils"
# rev = "c99762d7fd94bcc380e7d1a8a5e424cc93e77eca"
# ///
from cookies_site_utils import hoge
if __name__ == '__main__':
hoge()
# /// script
# requires-python = "==3.11.*"
# dependencies = [
# "cookies_site_utils @ git+https://github.com/CookieBox26/cookies-site-utils.git@c99762d7fd94bcc380e7d1a8a5e424cc93e77eca",
# ]
# ///
from cookies_site_utils import hoge
if __name__ == '__main__':
hoge()
上記のどちらでも、以下のように hoge() を実行できます。
$ uv run script.py
Welcome to Cookie's Site Utils!!
なお、このときにつくられた仮想環境を削除したいときは、以下のコマンド (スクリプトを実行せず依存パッケージのみインストールするコマンド) を実行すると仮想環境がインストールされたディレクトリが表示されるので、script-xxxxxx を削除すると削除できます (ディレクトリの確認や削除を直接実行するコマンドを見落としていたらご指摘ください)。
$ uv sync --script script.py
Using script environment at: C:\Users\user_name\AppData\Local\uv\cache\environments-v2\script-xxxxxx