Python 13：依存を記録して共有する ― GitHub にあげて他の人が使うとき

一言でいうと：料理ではなく、レシピを渡す

答えを先に言います。渡すのは「コード」と「必要なものの一覧」だけです。相手はその一覧を見て、自分のパソコンで箱（venv）を作り直し、PyPI から入れ直します。

料理にたとえると、こうなります。

できあがった料理（.venv）をそのまま運ぼうとすると、重いうえに崩れます（相手のパソコンでは絶対パスが合わない）。でも、レシピと材料の買える店さえ分かれば、相手は自分の台所で同じ料理を作れます。

これは JS でもまったく同じです。node_modules/ は GitHub に上げず、package.json と package-lock.json を上げて、相手が npm install で入れ直します。Python ではその「一覧」と「入れ直す道具」がいくつかあるので、順に見ていきます。

大事なのは、相手の手元に届くライブラリは、あなたのパソコンから来るのではなく、PyPI から来るということです。GitHub には、名前と版の一覧しか置きません。

上げるもの・上げないもの

具体的に、tenki のフォルダのどれを上げるのかを見ます（この章の tenki は、後で見る uv init で作った形です。コードは src/tenki/__init__.py に入っています。この形は第9章の src レイアウトです）。

実際に git が管理しているファイルを git ls-files で並べると、図の右のようになります。

$ git ls-files
.gitignore
.python-version
README.md
pyproject.toml
src/tenki/__init__.py
uv.lock

.venv は出てきません。第12章で見たとおり、venv は自分の中に * だけの .gitignore を置きますし、uv が作るプロジェクトの .gitignore にも .venv と書いてあるからです。

__pycache__/（第1章のバイトコードの置き場）も、同じ .gitignore で無視されています。これもそのパソコンで作り直せるものだからです。

「作り直せるものは上げない。作り直すための情報を上げる」。これが共有の基本の考え方です。

git push で、コードと一覧だけが GitHub へ

git push すると、図の小包のように、コードと一覧だけが GitHub に届きます。

git add .
git commit -m "tenki: 気温を表示"
git push

届くのは、どれも数KBの文字のファイルです。16MB の .venv は、あなたのパソコンに残ったままです。

GitHub のページで tenki のリポジトリを開いても、requests のコードはどこにもありません。あるのは pyproject.toml の中の "requests>=2.34.2" という1行の文字と、uv.lock の中の版と URL の記録だけです。

JS のリポジトリで node_modules/ が無いのと同じです。ライブラリの本体は、それぞれの公開場所（npm なら npmjs.com、Python なら PyPI）が持っています。

GitHub はあなたのコードの置き場、PyPI はみんなのライブラリの置き場。役割が分かれています。

相手は git clone。でも、それだけでは動かない

相手は、GitHub から tenki を取ってきます。

git clone https://github.com/you/tenki.git
cd tenki

図のように、相手のパソコンにはコードと一覧が届きました。でも、`.venv` はありません。requests も、どこにも入っていません。

この状態で動かそうとすると、第12章で見たおなじみのエラーになります。

$ python3 -c 'import requests'
ModuleNotFoundError: No module named 'requests'

pyproject.toml に requests と書いてあっても、Python は pyproject.toml を読んで勝手に入れてはくれません。import が見るのは sys.path のフォルダだけで、一覧のファイルは見ないからです（第8章）。

つまり、相手はもう1手、「一覧を読んで、箱を作って、入れる」をやる必要があります。

JS でも、git clone した直後に node index.js すると Cannot find module 'axios' になります。npm install を打つまで node_modules/ が無いからです。まったく同じ形です。

相手の手元で、一覧を見て箱を作り直す

相手がやることは、図の緑の .venv/ を自分のパソコンで作ることです。

図の小包は、PyPI から相手の .venv に届く requests 2.34.2 です。あなたのパソコンを経由していません。相手は PyPI から直接、同じ版の同じファイルを落としてきます。

できあがる .venv は、あなたの .venv とは別物です。中の絶対パスは相手のパソコンのもの（/home/friend/tenki/.venv/...）ですし、OS が違えば OS 用の部品も違います。でも、入っているライブラリの名前と版は同じです。だから tenki は同じように動きます。

この「一覧を読む・箱を作る・入れる」を、

どちらでも、中で起きていることは同じです。まずは昔からの pip のやり方で仕組みを見て、そのあと uv に進みます。

昔からの方法：pip freeze で requirements.txt を作る

いちばん古くからある一覧が、requirements.txt です。作り方は、箱に入っているものを `pip freeze` で書き出すだけです。

(.venv) $ pip freeze > requirements.txt
$ cat requirements.txt
certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0

pip freeze は「今この箱に入っているもの」を、1行に1つ「名前==版」の形で出します。> はシェルの機能で、出力をファイルに書き込みます。

相手は、それを使ってこう入れ直します。

git clone https://github.com/you/tenki.git
cd tenki
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py

-r は「このファイルに書いてあるものを全部入れて」という意味です。

この方法は今も広く使われていて、どんな Python にも pip さえあれば使えるのが強みです。uv を使っていても、uv export --format requirements.txt で同じ形のファイルを書き出せます。

ただし、freeze で作る一覧には弱点があります。次に見ます。

freeze の弱点：欲しかったものと、ついてきたものの区別がない

さっきの requirements.txt には5行ありました。でも、あなたが pip install したのは requests だけです。残りの4つは、requests が動くために必要で、一緒についてきたもの（依存、第11章）です。

freeze の一覧では、この5つが同じ顔で並びます。すると、困ることが出てきます。

そこで今は、一覧を2枚に分けるのが普通です。

JS を書いたことがあれば、この分け方はもう知っています。Python でも同じ形になった、ということです。

今の方法①：pyproject.toml に「欲しいもの」を書く

pyproject.toml は、Python のプロジェクトの説明書です。名前・版・必要な Python の版・依存するライブラリなどを書きます。JS の package.json にあたるファイルです。

[project]
name = "tenki"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "requests>=2.34.2",
]

dependencies に書くのは、あなたが直接 import するものだけです。certifi や idna は書きません。それは requests の説明書（requests 自身の依存の一覧）に書いてあり、入れるときに道具がたどってくれます（第11章）。

書き方は TOML という設定ファイルの形式です。[project] のような見出しの下に、キー = 値 を並べます。JSON と違ってコメント（#）が書け、最後の要素の後ろにカンマがあってもかまいません。

[project] の書き方は、Python のパッケージの決まり（packaging.python.org の pyproject.toml の仕様。元は PEP 621）で決まっていて、pip・uv・ほかの道具が同じように読めます。pyproject.toml には、ほかにも作ったものを配るための情報（第14章）や、道具の設定（第15章）も書けます。

版の範囲の書き方：>=・~=・==

dependencies の "requests>=2.34.2" の >=2.34.2 の部分を、版の指定（version specifier）と呼びます。よく使う書き方を、requests の版（2.31.0・2.32.3・2.32.9・2.34.2・3.0.0 のどれが入るか）で実際に確かめたのが図の表です。

~= は「互換の版」と呼ばれ、「書いた版以上で、最後の桁だけは上がってよい」という意味です。~=2.32 なら最後の桁は 32 の部分なので 2.x の中で上がってよく、~=2.32.3 なら 2.32.x の中だけです。

npm の ^1.7.0（1.x の中なら上がってよい）や ~1.7.0（1.7.x の中なら上がってよい）に近いですが、記号の意味は同じではありません。Python では ^ は使えません。

どう書くのがよいかは、何を作っているかで変わります。

uv add requests を打つと、uv は自動で >=（今の最新） の形で書いてくれます。

今の方法②：uv.lock に「実際に入れたもの」を全部書く

pyproject.toml の >=2.34.2 は「範囲」でした。範囲だけを渡すと、相手が入れるのはその日の最新になります。あなたが 2.34.2 で動かしたのに、相手は来月出た 2.35.0 を入れるかもしれません。

そこで、「今あなたの箱に実際に入っているもの」を、もう1枚のファイルに正確に書き残します。これがロックファイルで、uv では uv.lock です。中を開くと、こうなっています（requests の部分を抜き出したもの）。

[[package]]
name = "requests"
version = "2.34.2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "certifi" },
    { name = "charset-normalizer" },
    { name = "idna" },
    { name = "urllib3" },
]
wheels = [
    { url = "https://files.pythonhosted.org/.../requests-2.34.2-py3-none-any.whl", hash = "sha256:...", size = ... },
]

図の番号の順に、何が書いてあるかを見ます。

tenki の uv.lock は171行ありました。requests と4つの依存、そして tenki 自身のぶんです。charset-normalizer のように OS ごとに違うファイル（wheel）があるものは、Windows・macOS・Linux 用の URL と指紋が全部書いてあります。だから1つの uv.lock が、どの OS の相手にも使えます。

uv.lock は人が書くものではなく、uv が書くものです。uv のドキュメントも「手で直さないこと」「git に入れること」と書いています。

なぜ2つ？ pyproject は「幅」、uv.lock は「点」

2つのファイルの関係を、版の数直線で描いたのが図です。

相手が uv sync で入れるとき、uv は範囲の中の最新ではなく、ロックに書かれた点を入れます。だから、あなたと相手の箱の中身がそろいます。いつ・誰が入れても同じになる。これを再現できる（reproducible）と言います。

では、新しい版に上げたいときはどうするか。点を動かせばよいのです。

uv lock --upgrade-package requests   # requests だけ、範囲の中の最新に点を動かす
uv sync                              # 手元の .venv を新しい点に合わせる

動いたことを確かめたら、新しい uv.lock をコミットして push します。相手は pull して uv sync すれば、同じ新しい版になります。

幅と点を分けておくと、「どこまで上げてよいか（幅）」と「今どれを使っているか（点）」を別々に管理できる。2枚に分ける理由はこれです。

uv：venv と pip とロックを、1つの道具で

ここまでで、共有に必要な作業が出そろいました。

uv は、これらを1つにまとめた道具です。Astral という会社が作っていて、Rust という言語で書かれているので、とても速く動きます（pip で数秒かかるものが、ほぼ一瞬で終わることが多い）。

大事なのは、uv が新しい仕組みを持ち込んだわけではないということです。

uv が作る .venv は、第12章で見た venv と同じ形（bin/python・pyvenv.cfg・lib/python3.13/site-packages）をしています。入れるのも PyPI の同じ wheel で、site-packages に同じように展開します。pyproject.toml も標準の書き方です。中身は同じ仕組みで、手数と速さが違うだけです。

だから、ここまでの章で仕組みを知っていれば、uv で困ったときも .venv の中を開けて確かめられます。

uv そのものの入れ方は第2章を見てください。

uv init：プロジェクトの形を作る

新しく tenki を始めるところから、uv でやってみます。

$ uv init tenki
Initialized project `tenki` at `/home/you/tenki`

できたファイルを並べると、こうなりました。

.gitignore
.python-version
README.md
pyproject.toml
src/tenki/__init__.py

pyproject.toml には、ほかに [project.scripts] と [build-system] という見出しもあります。tenki = "tenki:main" は「tenki というコマンドで tenki パッケージの main 関数を呼ぶ」という意味で、uv run tenki で動かせるのはこのおかげです。この2つは、tenki を配れる形にする第14章で詳しく見ます。

uv init の直後には、まだ .venv も uv.lock もありません。必要になった瞬間に uv が作るからです。次の uv add で、それが起きます。

※uv 0.12 より前の uv init は、src/ を作らずに main.py を1つ置く形でした。古い記事と見た目が違うのはそのためです。

uv add requests：書く・固める・入れる を一度に

tenki に requests を足します。

$ uv add requests
Using CPython 3.13.7
Creating virtual environment at: .venv
Resolved 6 packages in 167ms
Installed 6 packages in 5ms
 + certifi==2026.7.22
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + tenki==0.1.0 (from file:///home/you/tenki)
 + urllib3==2.8.0

この1行で、図の番号の3つが起きました。

pip のやり方と比べると、「入れる」と「一覧に書く」が1手になったのが大きな違いです。pip では、入れた後で一覧を書き直すのを忘れると、「自分の手元では動くのに、相手のところでは動かない」になります。uv add はそれを起こしません。

.venv/lib/python3.13/site-packages/ を開くと、第12章と同じように requests/・requests-2.34.2.dist-info/ などが並んでいます。uv が作っても、置き場の形は同じです（uv の .venv には pip は入っていません。入れるのは uv の仕事だからです）。

6つ目の tenki==0.1.0 は、tenki 自身です。「ソースのフォルダを直接見る形（編集可能）」で箱に入っていて、コードを書き換えるとすぐ反映されます。この仕組みは第14章で見ます。

ライブラリをやめるときは uv remove requests で、一覧・ロック・箱の3つから一度に消えます。

uv run：確かめてから、箱の python で動かす

コードを書いたら、uv run で動かします。src/tenki/__init__.py の中身はこうです。

import requests

URL = "https://api.open-meteo.com/v1/forecast"


def main() -> None:
    params = {"latitude": 35.68, "longitude": 139.77, "current": "temperature_2m"}
    data = requests.get(URL, params=params, timeout=10).json()
    print(f"東京の気温: {data['current']['temperature_2m']}℃")

$ uv run tenki
東京の気温: 19.6℃

uv run は、動かす前に毎回、図の番号の順に確かめます（uv のドキュメントより）。

3の「.venv の python で」は、実際に確かめられます。

$ uv run python -c 'import sys; print(sys.executable)'
/home/you/tenki/.venv/bin/python3

activate していないのに、箱の python が動いています。第12章の「activate しなくても、箱の python をパスで指せば同じ」を、uv が代わりにやっているわけです。

uv run は uv run python main.py のように python に続けても、uv run pytest のように箱に入った道具の名前でも使えます。JS の npm run や npx に近い使い心地です。

相手の手元：git clone → uv sync → uv run

では、相手のパソコンに戻ります。uv があれば、相手がやることは3つだけです。

$ git clone https://github.com/you/tenki.git
$ cd tenki
$ uv sync
Using CPython 3.13.7
Creating virtual environment at: .venv
Resolved 6 packages in 1ms
Installed 6 packages in 4ms
 + certifi==2026.7.22
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + tenki==0.1.0 (from file:///home/friend/tenki)
 + urllib3==2.8.0
$ uv run tenki
東京の気温: 19.6℃

これは実際に、別の場所に clone して、uv のキャッシュも空の状態から試した結果です。あなたの uv add のときと、まったく同じ版が入りました。uv.lock に書かれた点どおりだからです。

図の3つの舞台を見直すと、ライブラリの本体は PyPI → 相手の `.venv` と動き、あなた → GitHub → 相手 の道を通ったのは文字のファイルだけです。

これが「GitHub にあげて他の人が使う時どうするの？」への答えです。コードと一覧だけを上げる。相手は clone して、自分の手元で箱を作り直して入れる。

相手が uv を使っていなくても、pyproject.toml は標準の書き方なので、pip でも pip install . のように読めます（プロジェクトを入れるこの形は第14章）。

ロックとずれていたら止める：uv sync --locked

uv sync と uv run は親切で、pyproject.toml と uv.lock がずれていると、ロックを書き直してから入れます。手元で作業しているときは、これが便利です。

でも、自動テスト（CI）や本番のサーバーで動かすときは、これが困ることがあります。誰かが pyproject.toml だけを直して、uv.lock を上げ忘れていたら、その場でロックが作り直され、あなたが確かめたのと違う版が入るかもしれないからです。

そこで、--locked を付けます。実際に、pyproject.toml だけを変えて試すとこうなりました。

$ uv sync --locked
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.

hint: To update the lockfile, run `uv lock`.

JS の npm install（必要なら lock を書き換える）と npm ci（lock とずれていたら止まる）の関係と同じです。

「ずれていたら黙って直す」と「ずれていたら止める」を、場面で使い分ける。これも再現できることを守るための仕組みです。

JS ではどうか：npm と並べる

ここまでの道具を、npm と並べます。

見比べると、uv は npm にかなり近い使い心地です。JS から来た人が uv を気に入りやすいのは、このためです。

違いは2つあります。

1つ目は、Python では「箱（venv）」が別の道具だったことです。Node.js は node_modules/ をファイルの場所から探すので、箱の出入りがありません（第12章）。uv は箱を自動で作り、uv run で箱の python を使うことで、この違いを見えにくくしています。

2つ目は、Python の版もそろえることです。uv は .python-version を見て、必要なら Python そのものも入れます。npm は Node.js の版まではそろえません（nvm などの別の道具を使います）。

仕組みを知っていれば、どの道具を使っていても「一覧」「記録」「箱」の3つを探せば、何が起きているか分かります。

よくある間違い：「自分の手元では動くのに」

共有したときに一番よく起きるのが、「自分の手元では動くのに、相手のところでは動かない」です。原因はたいてい、手元の箱と一覧がずれていることです。

1つ目は特に気づきにくいので、確かめ方を覚えておきましょう。

uv sync      # 一覧にないものは、箱から消される
uv run tenki # これで動けば、相手のところでも動く

uv sync は、既定ではuv.lock に無いものを箱から取り除きます。一覧に書き忘れたライブラリがあれば、ここで消えてエラーになるので、「相手のところで起きること」を自分の手元で再現できます。

どうしても pip のやり方で共有するなら、pip install の後に pip freeze > requirements.txt をし直して、それもコミットします。