wheel setuptoolsに関する備忘録

毎回仮想環境に入れがちな

python -m pip install --upgrade pip setuptools wheel

について何をしているのかが気になったのでまとめました。

端的に言うと

setuptools は「ソースコードをパッケージとして組み立てる道具」
wheel は「組み立てた結果を .whl という形式にするための道具・形式」

です。

setuptoolsなどのビルドバックエンドによってソースコードがビルドされ、結果として .whl 形式の wheel ファイルが作られ、pipでインストールしやすい形になります。

wheel はファイル形式に過ぎませんが、インストールも必要です。なぜなら、wheel という名前は .whl というファイル形式を指すだけでなく、その .whl ファイルを作成・扱うための Python パッケージ名でもあるからです。つまり、

wheel 形式      = .whl という配布ファイル形式
wheel パッケージ = .whl ファイルを作るための道具

という2つの意味があります。例えば .zip はファイル形式ですが、zip ファイルを作るには zip コマンドや zip ライブラリが必要です。それと同じで、.whl という形式のファイルを作るには、それを扱うための wheel パッケージが必要になることがあります。

そのため、ソースコードからパッケージをインストールする場合、pip は一度ソースをビルドして .whl ファイルを作り、その .whl をインストールします。この .whl を作る段階で、wheel パッケージが使われることがあります。

例えばsimplejsonをpipでソースからインストールすると以下のようなログになります。

$ pip install --no-binary=:all: simplejson
Collecting simplejson
  Downloading simplejson-4.1.1.tar.gz (118 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: simplejson
  Building wheel for simplejson (pyproject.toml) ... done
  Created wheel for simplejson: filename=simplejson-4.1.1-cp312-cp312-linux_x86_64.whl size=171407 sha256=f3d1ef3884bf95c79b5d9a286fab59567fe187daa738fed389e0e85d644c857a
  Stored in directory: /shared/home/hpcadmin/.cache/pip/wheels/d0/a9/9c/be246019d19c0a733490606b19731c7ad30d8b06136ef63e47
Successfully built simplejson
Installing collected packages: simplejson
Successfully installed simplejson-4.1.1

[notice] A new release of pip is available: 26.0.1 -> 26.1.1
[notice] To update, run: pip install --upgrade pip

このログでは、simplejson-4.1.1.tar.gz というソースコードを取得しているため、最初から .whl が用意されていたわけではありません。

Downloading simplejson-4.1.1.tar.gz

その後、simplejson-4.1.1.tar.gzを解凍して中身を見て pyproject.toml に基づいてビルドに必要な依存関係を準備し、wheel を作るためのメタデータを確認しています。この際にsetuptoolsが裏で動いています。

Installing build dependencies ... done
Getting requirements to build wheel ... done
Preparing metadata (pyproject.toml) ... done

そして、実際にソースコードから wheel を作成しています。この段階で .whl 形式の配布ファイルが作られています。

Building wheel for simplejson (pyproject.toml) ... done
Created wheel for simplejson: filename=simplejson-4.1.1-cp312-cp312-linux_x86_64.whl

ここで作られた

simplejson-4.1.1-cp312-cp312-linux_x86_64.whl

が、手元の環境で生成された wheel ファイルです。ソースコードを引っ張ってきて、自分の環境で動く手筈が整ったわけですね。

つまり、このログでは次の流れが起きています。

simplejson のソースコードを取得
        ↓
setuptools などのビルドバックエンドが pyproject.toml を読む
        ↓
ソースコードをビルドする
        ↓
wheel 形式の .whl ファイルを作る
        ↓
pip がその .whl をインストールする

最後に、

Successfully built simplejson
Installing collected packages: simplejson
Successfully installed simplejson-4.1.1

とあるので、ソースコードから wheel の作成に成功し、その wheel を pip が仮想環境にインストールしたことがわかります。

つまり、setuptools と wheel を事前に入れておく意義は、ビルド済み wheel が見つからない場合や、今回のように --no-binary=:all: であえてソースから入れる場合に、ソースコードをインストール可能な wheel 形式へ変換できるようにすることです。

一方で、有名なライブラリはビルド済みのwheelがすでに存在していることが多く、pipでそのままインストールできるため、わざわざ手元でオリジナルのwheelをsetuptoolsやwheelを使って作成する意味はないわけですね。

まとめると、

ビルド済み wheel がある場合:
  pip が .whl を取得してそのままインストール

ビルド済み wheel がない場合:
  pip がソースを取得
  setuptools などでビルド
  wheel 形式の .whl を作成
  pip がその .whl をインストール

となります。

そのため、

python -m pip install --upgrade pip setuptools wheel

は、環境によってソースビルドが必要になり得るライブラリを入れる前に、Python パッケージをビルドして wheel 化するための基本ツールを整えるコマンドだと言えます。