Python 02：入れ方とバージョン

一言でいうと：同じ名前の役者が何人もいて、PATH が出番の順番表

第1章のたとえを続けます。python3 は台本を演じる役者でした。実は、この役者は同じ名前で何人いてもかまいません。Homebrew が連れてきた python3、python.org から来た python3、Apple が最初から置いていた python3。みんな名前は python3 です。

では、あなたが python3 main.py と打ったとき、誰が舞台に上がるのでしょうか。

シェルは順番表を持っています。それが環境変数 PATH です。PATH には「役者を探しに行く楽屋（フォルダ）」が順番に並んでいて、シェルは上から順に楽屋をのぞき、python3 という名前の役者を最初に見つけたところで呼びます。

図では、2番目の楽屋 /opt/homebrew/bin に Homebrew の python3 がいたので、その人が呼ばれました。3番目・4番目の楽屋にも python3 はいますが、呼ばれることはありません。

大事なのは、役者が何人いても困らないということです。困るのは、「自分が呼んだつもりの役者」と「実際に舞台に上がった役者」が違うときだけです。この章では、その食い違いを自分で見つけられるようになることを目指します。

Python の入れ方は、主に3つ（＋最初から入っているもの）

Python の入れ方はいくつもありますが、Mac でよく使われるのは次の3つです。

どれで入れても、中身は第1章で見た CPython です。python.org が配っているソースから作られた、同じ Python です。違うのは次の2点だけです。

Linux では、ディストリビューション（Ubuntu など）が /usr/bin/python3 を最初から入れていることが多く、これも Mac の Apple のものと同じく「OS が使うもの」です。Windows では、python.org の配布物などに py という起動用のコマンドが付いていて、py -3.13 のように版を指定して呼べます。この本のコマンドは macOS と Linux で書きます。

python.org で入れると：Frameworks に本体、/usr/local/bin に入口

python.org からダウンロードしたインストーラーで Mac に入れると、Python の公式ドキュメントにあるとおり、次のように置かれます。

シンボリックリンクとは、「本物はあっちにあるよ」と指し示すだけの小さなファイルです。ショートカットや別名のようなものだと思ってください。/usr/local/bin/python3 を実行すると、実際には Frameworks の中の本体が動きます。

なぜわざわざ入口を別に置くのでしょうか。それは、/usr/local/bin が最初からPATH に入っていることが多いフォルダだからです。本体の深い場所を PATH に足さなくても、python3 と打つだけで呼べるようにしているのです。

入れた直後に1つだけやることがあります。/Applications/Python 3.13/ の中の Install Certificates.command をダブルクリックして実行することです。これは、Python が HTTPS で通信するときに相手が本物かを確かめるための証明書を入れる作業です。これを忘れると、後で requests などで HTTPS のサイトにつなぐときに証明書のエラーが出ることがあります。

Homebrew で入れると：/opt/homebrew/bin に並ぶ

Mac の道具を Homebrew で揃えている人は、Python も Homebrew で入れることが多いでしょう。

$ brew install python
$ which python3
/opt/homebrew/bin/python3

Apple Silicon（M1 以降）の Mac では、Homebrew は /opt/homebrew/ の下に物を置き、コマンドを /opt/homebrew/bin/ に並べます。Intel の Mac では /usr/local/ の下です。node や git を Homebrew で入れていれば、それらと同じ棚に python3 が並ぶことになります（第1章で which node と同じフォルダが出たのはこのためです）。

Homebrew の Python には、知っておくべき癖がいくつかあります。

3つ目は、JS で言えば「brew で入れた node が勝手に新しくなって、node_modules の一部が動かなくなった」のと似た事故です。そのため、プロジェクトで使う Python の版を自分で決めて固定したいときは、次の uv のほうが向いています。

uv で入れると：自分のホームの下に、版ごとに並ぶ

uv は、Python のパッケージ管理を速く・まとめてやるための道具です（第13章で詳しく見ます）。uv は、ライブラリを入れるだけでなく、Python 本体を入れることもできます。この本を書いた Linux で実際に試した結果がこちらです。

$ uv python install 3.13
Installed Python 3.13.7 in 2.46s
 + cpython-3.13.7-linux-x86_64-gnu (python3.13)
$ ls -l ~/.local/bin/python3.13
... python3.13 -> /root/.local/share/uv/python/cpython-3.13.7-linux-x86_64-gnu/bin/python3.13

uv の公式ドキュメントによれば、uv は Python を自分で一から作るのではなく、python-build-standalone という、あらかじめ作っておいた持ち運びやすい CPython をダウンロードして置いています。Mac でも同じ仕組みで、フォルダ名の linux-x86_64-gnu の部分が Mac 用の名前になります。

ポイントは、入口として置かれるのが python3.13 という版の番号付きの名前だけだということです。python3 や python という名前は、uv python install --default と付けたときだけ置かれます（uv のドキュメントでは、この --default はまだ試験的な機能とされています）。つまり uv は、あなたが今まで使っていた python3 を勝手に乗っ取りません。

さらに uv は、必要な版が入っていなければ、その場で自動でダウンロードしてくれます。版の違う Python を何個でも並べられるので、「このプロジェクトは 3.12、あちらは 3.13」という使い分けが楽になります。

1台のパソコンに、何個もの Python が同居している

ここまでで、置き場所がばらばらなことが分かりました。置き場所が違うので、何個入れてもお互いにぶつかりません。実際、この本を書いた Linux で uv python list --only-installed と打つと、次のように何個も見つかりました（読みやすく一部を省略しています）。

cpython-3.13.12-linux-x86_64-gnu    /usr/bin/python3.13
cpython-3.13.7-linux-x86_64-gnu     ~/.local/bin/python3.13 -> ~/.local/share/uv/python/…
cpython-3.12.3-linux-x86_64-gnu     /usr/bin/python3.12
cpython-3.11.15-linux-x86_64-gnu    /usr/local/bin/python3 -> /usr/bin/python3.11
cpython-3.10.20-linux-x86_64-gnu    /usr/bin/python3.10

5つも入っています。ところが、この環境で python3 と打って動くのは 3.11 です。なぜ、新しい 3.13 ではないのでしょうか。

答えは、python3 という名前の入口が、PATH の順で最初に見つかるのが /usr/local/bin/python3 で、それが 3.11 を指しているからです。3.13 は python3.13 という別の名前で呼ばないと出てきません。

新しい版を入れたのに古い版が動く、というのはよくあることです。それは「入っていない」のではなく、「呼ばれていない」のです。次に、その「呼ばれる順番」である PATH を、1段ずつ見ていきます。

PATH は「コマンドを探すフォルダ」を : でつないだ1行の文字

PATH は、シェルが覚えている環境変数の1つです。環境変数とは、シェルや、シェルから起動したプログラムが読める「名前つきの文字」のことです。中身は echo $PATH で見られます。

$ echo $PATH
/Users/you/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin

ただの1行の文字です。:（コロン）で区切られた1つ1つが、コマンドを探しに行くフォルダです。図では、Mac に python.org・Homebrew・uv の3つで Python を入れた場合の例を、4枚のカードに並べました。

PATH の中身は、シェルが起動するときに読む設定ファイルで決まります。Mac の zsh なら ~/.zprofile や ~/.zshrc、Linux の bash なら ~/.bashrc などです。Homebrew や uv を入れたときに「この行をシェルの設定に足してください」と言われたことがあるなら、それはこの PATH に自分のフォルダを足すためでした。

JS で nvm を入れたときにも、同じように設定ファイルに行を足したはずです。あれも、nvm の置いた node を PATH で見つけられるようにするためです。

シェルは左から探し、最初に見つかった python3 を起動する

では、python3 と打ったときに何が起きるかを、図の小包で追ってみます。

大事なことが2つあります。

1つ目は、名前が完全に一致するものだけが当たることです。~/.local/bin には python3.13 がありますが、python3 とは別の名前なので素通りします。逆に python3.13 と打てば、1番目のフォルダで見つかり、uv の 3.13 が動きます。

2つ目は、最初の1つが見つかったら、そこで探すのをやめることです。3番目・4番目にも python3 はありますが、シェルはもう見に行きません。だから、Python がいくつ入っていても、python3 と打って動くのは常に1つだけです。

ちなみに、zsh や bash は、一度見つけたコマンドの場所を覚えておくことがあります。新しく Python を入れたのに古い場所のものが動き続けるときは、ターミナルを開き直すか、zsh なら rehash、bash なら hash -r と打つと、探し直してくれます。

PATH の並びを変えると、呼ばれる python3 が変わる

PATH の並びを変えると、同じ python3 と打っても、別の Python が動きます。試しに、/usr/local/bin を先頭に足してみます。

$ export PATH="/usr/local/bin:$PATH"
$ echo $PATH
/usr/local/bin:/Users/you/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin
$ which python3
/usr/local/bin/python3

export PATH="フォルダ:$PATH" は、「今の PATH の先頭にフォルダを足す」という意味です。$PATH の部分に今までの中身が入るので、/usr/local/bin が2回出てきますが、先に見つかるほうが使われるだけなので問題はありません。

図では、カードの並びが変わり、先頭に来た python.org の python3 が呼ばれるようになりました。入っているものは何も変わっていません。変わったのは並びだけです。

この「PATH の先頭にフォルダを足して、呼ばれるコマンドを差し替える」という技は、この本でもう一度、大事な場面で出てきます。第12章の仮想環境で source .venv/bin/activate と打つとき、裏でやっていることはこれとほとんど同じです。activate は魔法ではなく、PATH の先頭に .venv/bin を足しているだけなのです。

今どれが呼ばれるかは、3つのコマンドで確かめる

PATH の仕組みが分かったら、「今、どれが呼ばれるのか」を確かめる方法を持っておきましょう。この本を書いた Linux で実際に打った結果です。

$ which python3
/usr/local/bin/python3
$ which -a python3
/usr/local/bin/python3
/usr/bin/python3
/bin/python3
$ python3 -c "import sys; print(sys.executable)"
/usr/local/bin/python3

which はシェルの側から見た答え、sys.executable は Python の側から見た答えです。`sys` は Python に最初から入っている標準ライブラリの1つで、動いている Python 自身についての情報を持っています。

普段はどちらも同じ答えになりますが、エディタから実行したとき、別の道具から起動されたときなどは、sys.executable のほうが確実です。プログラムの中に一時的に print(sys.executable) と書いておけば、「このコードを、どの Python が動かしているのか」を必ず確かめられます。

zsh では which -a の代わりに where python3、bash では type -a python3 でも同じように候補の一覧が見られます。

python と python3：名前が2つあるのは、昔の Python 2 のなごり

なぜ Python には python と python3 という2つの名前があるのでしょうか。

理由は歴史にあります。Python 3 は、Python 2 と書き方に互換性のない大きな変更でした。そのため長い間、1台のパソコンに Python 2 と Python 3 が同居していて、python と打つと Python 2、python3 と打つと Python 3 が動く、という呼び分けが広まりました。Python 2 はすでに 2020 年に開発が終わっていますが、この呼び分けは今も残っています。

Mac で python と打って zsh: command not found: python と言われるのは、これが理由です。ネットの記事で python main.py と書いてあっても、Mac では python3 main.py と読み替えてください。

逆に、第12章で作る仮想環境を有効にした後は、python という名前が使えるようになり、python でも python3 でも同じものが動きます。多くの記事が python と書いているのは、仮想環境の中で作業している前提だからです。

JS には node2 と node3 のような呼び分けはありませんでした。ここは Python 特有の事情です。

pip と打つと、別の Python の pip が動くことがある

Python のライブラリを入れる道具 pip も、python3 と同じように PATH で探されるただのコマンドです。そして、ここに落とし穴があります。この本を書いた Linux で実際に打った結果を見てください。

$ pip --version
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.11)
$ python3.13 -m pip --version
pip 24.3.1 from /root/.local/share/uv/python/cpython-3.13.7-linux-x86_64-gnu/lib/python3.13/site-packages/pip (python 3.13)

行の最後の (python 3.11) と (python 3.13) に注目してください。これは「この pip は、どの Python のためにライブラリを入れるか」です。

もし pip install requests と打ってから python3.13 main.py で実行すると、requests は 3.11 の置き場所に入り、3.13 はそれを探せません。結果は ModuleNotFoundError: No module named 'requests' です。入れた Python と、動かした Python が別人だったのです。

pip は Python ごとに1つずつあり、「自分の Python の置き場所」にだけライブラリを入れます。ライブラリの置き場所（site-packages）の話は第11章で詳しく見ますが、ここでは「pip と python3 は、別々に PATH で探される」ことだけ押さえてください。

python3 -m pip は「この python3 の pip」と名指しする書き方

この食い違いを防ぐのが、第1章でも少し出てきた -m です。python3 -m pip install requests と打つと、次の順で動きます。

Python の公式ドキュメントによれば、-m は「モジュールを sys.path から探して、その中身を実行する」オプションです。`sys.path` は「その Python が探しに行くフォルダの一覧」で、第8章の主役です。大事なのは、sys.path はPython ごとに違うということです。だから python3.13 -m pip と書けば、必ず 3.13 の pip が動きます。

つまり python3 -m pip は、「PATH で python3 を探すのは1回だけにして、pip はその python3 自身に選ばせる」書き方です。探す回数が1回になるので、食い違いが起きません。

pip の公式ドキュメントでも、コマンドの例は python -m pip の形で書かれています。この本でも、pip は基本的に python3 -m pip と書きます。

Mac に最初からある Python には、触らない

Mac には、何もしなくても /usr/bin/python3 があります。Python の公式ドキュメントには、これについて次のような説明があります。

具体的にやってはいけないのは、/usr/bin/python3 を消す・置き換えることと、sudo pip install で中にライブラリを足すことです。OS や他の道具が前提にしている状態を壊してしまいます。代わりに、自分用の Python を別に入れて、そちらを使います。前に見た3つの入れ方は、どれもそのためのものです。

同じ考え方を、Python の世界は仕組みとして持っています。PEP 668（Python の改善提案の668番）で決められた「外部で管理されている環境」の印です。OS や Homebrew、uv が管理する Python にはこの印が付いていて、pip で直接入れようとすると断られます。uv で入れた Python で実際に試した結果がこちらです。

$ python3 -m pip install requests
error: externally-managed-environment

× This environment is externally managed
╰─> This Python installation is managed by uv and should not be modified.

このエラーが出たら、「ここに直接入れるな、仮想環境（venv）を作ってその中に入れなさい」という意味です（第12章）。--break-system-packages を付ければ無理やり入れられますが、名前のとおり壊す危険があるので使いません。

この本のおすすめ：uv で Python を入れ、プロジェクトごとに版を決める

入れ方はどれを選んでも、仕組みは同じです。そのうえで、この本では uv をおすすめします。

uv そのものは、公式の手順どおり1行で入れられます（Homebrew を使っているなら brew install uv でも入ります）。そのあと、tenki で使う版を決めます。この本を書いた環境で実際に打った結果です。

$ curl -LsSf https://astral.sh/uv/install.sh | sh
$ uv python install 3.13
$ cd tenki
$ uv python pin 3.13
Pinned `.python-version` to `3.13`
$ cat .python-version
3.13
$ uv run python --version
Python 3.13.7

uv python pin 3.13 は、今いるフォルダに .python-version という1行だけのファイルを作ります。以後、このフォルダで uv run python ... と打つと、uv がこのファイルを読んで 3.13 を選んで動かします。PATH でどの python3 が先に見つかるかに関係なく、プロジェクトが自分の版を決められるのです。

この「uv run」の中で何が起きているかは、仮想環境（第12章）と依存の管理（第13章）を見た後で分解します。今はまず、python3 が何者かを確かめられることのほうが大事です。

JS との対比：nvm と .nvmrc、uv と .python-version

ここまでの話は、JS の世界にもほとんどそのまま対応するものがあります。

JS 側の仕組みも一言で説明し直しておくと、nvm は Node.js の版ごとに別のフォルダに置き、nvm use 20 と打つと、PATH の先頭をその版のフォルダに書き換えます。だから node と打つと 20 系が動くのです。

Python でも、考え方は全く同じです。「版ごとに別の場所に置き、PATH で入口を差し替える」。違うのは道具の名前だけです。

1つだけ違うのは、Python には「Mac に最初から入っている Python」がある点です。Node.js は最初から入っていないので、自分で入れたものしかありません。Python では、自分で入れたものと OS のものが同じ `python3` という名前で並ぶので、PATH の順番がより大事になります。

よくある間違い：入れたのに、無いと言われる

この章の知識で解けるエラーを並べます。ほとんどの原因は、「入れた Python」と「動かした Python」が別人であることです。

1つ目のエラーは、この本の中で何度も出てきます。第8章では「Python はどのフォルダを探して、見つからなかったのか」、第11章では「pip はどのフォルダに置いたのか」という両側から見て、完全に分解します。

ここでは、エラーが出たらまず「どの Python が動いたのか」を確かめる、という習慣だけ身につけてください。確かめ方は次にまとめます。

困ったら、まずこの3行

Python の環境で迷子になったら、まず次の3行を打ちます。

$ which -a python3
$ python3 -c "import sys; print(sys.executable, sys.version)"
$ python3 -m pip --version

この3行で、「どの python3 が、どの版で、どの pip とつながっているか」が分かります。ほとんどの迷子は、この3つのどこかに食い違いがあります。

tenki では、uv で版を決めたので、確かめ方も簡単です。tenki のフォルダで次のように打ちます。

$ uv run python --version
Python 3.13.7

.python-version に書いた 3.13 が使われていることが分かります。第12章以降、仮想環境を使うようになると、確かめる場所が「PATH の上の python3」から「.venv/bin/python」に変わりますが、確かめ方の考え方は同じです。