拡張子ナビFILE EXTENSION LIBRARY
English
ホーム›Web・開発›.whl
ファイルを知る、使いこなす。
.whl

Python Wheelパッケージ

Web・開発

WHLはPython Wheelの配布パッケージです。ZIP構造ですが、展開するだけで正しく導入できるとは限りません。Python版、ABI、OS・CPUの互換性タグを確認し、目的の仮想環境のpipで扱います。「not a supported wheel」の原因を具体的に切り分けます。

主な用途
Pythonパッケージを対応環境へ導入する
中身の種類
コードを含む導入・実行形式
目次・よくある質問・根拠資料を見る

内容の最終確認： · 編集：Kai

具体例：確認する順番

例：Wheelが「not a supported wheel」と表示される場合。Python版、ABI、OS・CPUの三つの互換条件と実行中のPythonを比較します。cp310をcp311へ改名せず、正規の適合ビルドを取得します。目的の仮想環境のpython -m pipで導入し、同じPythonで動作確認します。仮想環境だから未知のコードも安全とは考えません。

開き方・操作手順

使っている環境や目的の項目を開いて、手順を確認してください。

メタデータと互換性を確認

確認とパッケージ導入は別です。

  1. 正規の配布元とファイル名の互換性タグを確認します。
  2. 対象Pythonの版、実装、OS、CPUを確認します。
  3. 必要ならZIP対応ツールで一覧やメタデータを閲覧し、コードを実行しません。
仮想環境へpipで導入

使うPython環境を明示します。

  1. 正規パッケージと依存条件を確認し、目的の仮想環境を有効にします。
  2. そのPythonの「python -m pip」でローカルWheelを指定して導入します。
  3. 同じ環境でパッケージ情報と必要な動作を確認します。

操作名・対応状況はアプリ・OS・版によって異なります。変更する前に原本を残してください。

開けないとき：症状から確認

  • not a supported wheel：Python、ABI、OS・CPUのタグ不一致を確認します。
  • 別のPythonへ入った：pipの実行元と利用するPythonを揃えます。
  • 32/64bitが違う：OSだけでなくPython自体のアーキテクチャも確認します。
  • 導入後に依存がない：正規の依存条件と導入環境を確認します。
  • cp310等を改名しても失敗：対応バイナリが変わるわけではありません。正しいビルドを取得します。

WHLは正しいビルドを選ぶ

  1. 対象環境のPython版・OS・CPUを確認します。
  2. 配布元の対応Wheelを選び、指定環境のpipで導入します。
  3. 別環境へ渡すときは対応条件と依存一覧を記録します。

ファイル名のタグ変更は互換性の修正ではありません。ソースからのビルドが必要な場合は別の開発作業です。

Wheel名の3つの互換性タグ

Wheel名にはPython、ABI、プラットフォームのタグがあります。pure Python向けの汎用Wheelと、特定CPythonやOS向けのバイナリWheelを区別します。

この手順の根拠：Python Packaging Authority · Platform compatibility tags

仮想環境とpipを揃える

「pip」とだけ実行すると、別のPython環境のものを使う場合があります。対象Pythonからモジュールとしてpipを起動すると、環境を明示しやすくなります。

  • 対象版を確認してから導入。
  • 必要な依存も正規配布から取得。
  • システムPythonへ不用意に全体導入しない。

この手順の根拠：pip project · pip install / Python Packaging Authority · Binary distribution format

関連形式との違い

関連形式との違い
形式・用途使い分けと残る情報
WHL導入用のビルド済み配布物。
PYPythonのソースコード。
ZIP汎用アーカイブ。Pythonへの登録は別。

取り扱いと安全性

WheelにはPythonコードやネイティブライブラリが含まれます。仮想環境はセキュリティ隔離そのものではないため、正規配布元を確認して導入します。

よくある質問

ZIPへ展開すれば使える？

pipの導入処理や依存管理とは別です。

cpタグを書き換えていい？

バイナリ互換は変わりません。適切なビルドを取得します。

64bit Windowsなら全部対応？

Python版、ABI、CPU等も確認します。

python -m pipを使う理由は？

対象Python環境を明示するためです。

仮想環境なら不明なWheelも安全？

仮想環境はセキュリティ隔離ではありません。出所を確認します。

形式の基本情報：正式名称・MIME type・管理団体
名称
Python Wheel Distribution
管理・仕様
Python Packaging Authority
MIME type
統一された値として扱わず、作成元・実装の資料を確認してください。

公式・一次情報

  • 標準仕様Binary distribution format

    WheelのZIP構造とメタデータ

    Python Packaging Authority · リンク確認：
  • 標準仕様Platform compatibility tags

    Python版・ABI・OS/CPUの互換性タグ

    Python Packaging Authority · リンク確認：
  • プロジェクト公式pip install

    Wheelを選択したPython環境へ導入

    pip project · リンク確認：