Qiskit v1.0 パッケージの破壊的変更を理解する
Qiskit v1.0 は以前のバージョンとは異なるパッケージ構成を採用しており、Qiskit v1.0 に対応していないパッケージを使用している環境では問題が発生する可能性があります。
既存の Python 仮想環境をその場で Qiskit v1.0 にアップグレードしようとしないでください。
今後は同様の破壊的なパッケージ変更は行いません。これは Qiskit v1.0 のリリース時に限った一度限りの変更であり、将来のパッケージ管理をできる限り簡単にするために行ったものです。
このページでは、v1.0 以前の Qiskit パッケージの詳細情報と、破壊的なパッケージ変更を行った理由について説明します。
この変更が不便をおかけすることは承知していますが、これによって Qiskit はほとんどの Python パッケージが採用しているシンプルなパッケージ構成に戻ります。Qiskit v1.0 への移行が完了すれば、ユーザー、開発者、ライブラリ作者にとってより使いやすい環境になります。
前置き: Python パッケージング用語集
旧来の Qiskit メタパッケージの構成と、Qiskit v1.0 のリリースによってそれがどのように変化したかをより分かりやすく説明するために、よく使われる Python パッケージング用語の用語集を以下に示します。このドキュメントでは、以下の語を特定の意味で使用します。
クリックしてこのページの用語集を読む
-
モジュール (module): 単一の Python ファイルです。
-
パッケージ (package):
__init__.pyとその他のファイルやパッケージを含むディレクトリで、Python が読み込めるものです 。 これはコンピュータにインストールされた実際のコードであり、import somethingを実行したときに動作するものです。 Python は検索パス上にあるディレクトリをインポート可能なものとして扱います（さらに多くの項目もインポートします）。これは
pip installでインストールするもの（ディストリビューション）と同じではありませんが、通常はpip installするものとimportするものは同じ名前を持ちます。 -
サブモジュール (submodule)、サブパッケージ (subpackage): 不正確な用語ですが、広く使われています。 sub の部分は「パッケージ内に含まれる」という意味です。 サブモジュールはモジュールであり、サブパッケージはパッケージですが、どちらもより大きなパッケージの一部です。
-
名前空間パッケージ (namespace package): 他の ディストリビューション によってサブモジュールやサブパッケージをインストールできるパッケージです。 重要な点として、名前空間パッケージに寄与するディストリビューションは必ずしもインストールされたすべてのファイルを所有するわけではないため、完全なアンインストールやアップグレードが難しい場合があります。
-
ディストリビューション (distribution):
pip install somethingを実行したときにダウンロードされる、圧縮された Python ファイル、データファイル、およびメタデータです。 通常、ディストリビューションはちょうど一つのパッケージとそのインストール方法に関するメタデータ（依存関係など）を含みますが、これは必須ではありません。 ディストリビューションはモジュールやパッケージを 0 個以上含むことができます。apt（Debian/Ubuntu）や macOS の Homebrew など、Python 以外の「パッケージマネージャー」に馴染みがある場合、それらで「パッケージ」と呼ばれるものが Python では「ディストリビューション」に相当し、Python の「パッケージ」に完全に対応するものはありません。Python パッケージングに関するほとんどの資料では、パッケージ という言葉をディストリビューションとパッケージの両方の意味で使用しており、文脈から判断する必要があります。 一般的に、
importするものは「パッケージ」を指し、pip installするものは「ディストリビューション」を指します。 -
検索パス (search path):
import somethingを実行したとき、Python はsomethingという名前のモジュールまたはパッケージを事前定義されたリストの場所から検索します。 その場所のリストが 検索パス です。 検索パスはsys.pathで確認・変更できます。 -
依存関係 (requirement): ディストリビューションには、インストール時に依存する他のディストリビューションの情報が含まれています。 必要な他のディストリビューションを 依存関係 と呼び、パッケージマネージャー（通常は
pipまたはconda）がすべての依存関係を互換性のあるバージョンでインストールします。
Python は高度に動的であり、さまざまな複雑な状況が生じる可能性があります 。例えば、モジュールやパッケージがディスク上のファイルと対応しない場合や、コンパイル済み拡張モジュールである場合があります。
検索パスはディレクトリに対する検索だけではありませんが、この説明ではディスク上のファイルのみが関係します。 このセクションで説明する問題を理解するためにそれ以上の複雑さを考慮する必要はないため、上記のモデルで十分です。
旧来の Qiskit の構成
歴史的に、Qiskit は複数の Python ディストリビューションで構成されていました。コンパイラコアである qiskit-terra、高性能シミュレーターである qiskit-aer、オリジナルの IBM Quantum® プロバイダー、そして特定の試験的なアルゴリズムや実験実行機能を提供するいくつかの現在は廃止されたパッケージです。
ユーザーの利便性のために、コードを一切含まないものの、他のすべてのコンポーネントをインストールさせる qiskit という Python ディストリビューションも提供していました。
他のパッケージマネージャーの類似概念との類比から、これを メタパッケージ と呼んでいました。
Qiskit のコアは qiskit-terra に存在し、Python パッケージ qiskit のルートを所有していました。言い換えると、import qiskit を実行したときの動作は qiskit-terra が制御していました。
Qiskit v1.0 以前は、qiskit パッケージは名前空間パッケージであり、qiskit.providers に第 2 の名前空間パッケージを含んでいました。
この構成は私たちとユーザーにかなりの問題をもたらしました。
例えば、Qiskit に依存するダウンストリームライブラリは、実際にはコンパイラコアのみを必要とし、pip install qiskit によってインストールされる大規模なエコシステム全体を必要としないことが多くありました。
そのため、依存関係を正しく qiskit-terra と指定するのが適切でした。
しかし、pip uninstall qiskit を実行して Qiskit をアンインストールしようとすると、pip はいくつかの問題に遭遇しました：
pipは不要になったディストリビューションを削除しません。そのため、pip uninstall qiskitはほとんど何も行いませんでした。ディストリビューションにはコードが含まれていなかったため、コードも削除されませんでした。- 仮にコードが削除されたとしても、多くのダウンストリームディストリビューションは
qiskit-terraに依存しているため、インストールされたまま残ります。 qiskit-terraがアンインストールされた場合でも、名前空間パッケージであるため、使用可能なコードを持たないqiskitディレクトリがインポート可能な状態で残る場合があります。
pip install コマンドでディストリビューションをインストールまたはアップグレードする際、pip は以前の依存関係の解決結果を考慮しません。
2 つのパッケージが存在したため、qiskit-terra のアップグレードを必 要とするパッケージをアップグレードすると無効な環境が生まれました。pip は qiskit-terra をアップグレードしましたが、qiskit はそのまま残しました。
この件について、その後のすべての pip install コマンド実行時に警告が表示されましたが、何も壊れているように見えなかったため、ユーザーは通常その警告を無視し、pip はエラーを発生させたり操作を禁止したりしませんでした。
時間をかけて、qiskit メタパッケージからコンポーネントを順次削除し、Qiskit v0.44 以降は qiskit-terra のみが残るようになりました。
これらのコンポーネントのうち、qiskit-aer は現在も存在しており積極的に更新されていますが、現在は独立したディストリビューションとしてインストールされます。
同様に、他のライブラリに対して名前空間フックの使用をより強く非推奨としました。
最後の Qiskit による名前空間フックの使用を、廃止されていないパッケージから削除したのは Qiskit Aer v0.11 のリリース時であり、この際に新しい qiskit_aer Python パッケージが導入されました。ただし Qiskit v1.0 以前は qiskit.providers.aer という名前空間パスも強制的に機能させていました。
Qiskit v1.0 以降は、パッケージが qiskit 名前空間を拡張する機能を削除しました。これにより、有効な環境において正しいディストリビューションに対して pip uninstall を実行することが期待通りに機能するようになりました。
新しい Qiskit の構成
バージョン 1.0 以降、Qiskit は qiskit という単一のディストリビューションで構成されており、これも qiskit という一つのパッケージをインストールし、そのディレクトリ内のすべてのコードを所有します。
これは Python コードの標準的な構成であり、最もシンプルでエラーが起きにくい構成です。
PyPI 上の qiskit-terra ディストリビューションはバージョン 1.0 以降には更新されません。qiskit によって完全に置き換えられています。
インストールにおいて qiskit-terra という名前はもはや使用されません。
ただし、qiskit-terra パッケージは PyPI から削除されず、最新バージョンを動作する状態で維持するため、古い科学的コードやレガシーパッケージが引き続き使用できるようにします。
残念ながら、メタパッケージのレガシーと pip パッケージマネージャーの欠点により、Qiskit v1.0 への完全にスムーズなアップグレードパスを提供することは不可能です。特に、一部のパッケージが以前のバージョンの Qiskit に依存し、また一部が Qiskit v1.0 以上のみを必要とする場合はなおさらです。
エコシステムの多くが Qiskit v1.0 に移行するにつれて、これらの問題は軽減されていきます。
アプリケーションモジュールはどこへ？
pip install qiskit コマンドでは、qiskit-aer や qiskit-nature などのパッケージがインストールされなくなったことに気づかれた方もいるかもしれません。メタパッケージ構成の廃止に伴い、これらのパッケージの多くは個別にインストールが必要なディストリビューションとして分離されました。
Qiskit SDK v1.0 のリリース以前、Qiskit はコンパイラコアである qiskit-terra、高性能シミュレーターである qiskit-aer、オリジナルの IBM Quantum® プロバイダー、そして特定の試験的なアルゴリズムや実験実行機能を提供するいくつかの現在は廃止されたパッケージなど、多くの異なる Python ディストリビューションで構成されていました。
以前 Qiskit メタパッケージに含まれていたパッケージをインストールしたい場合は、Qiskit エコシステムにアクセスして、ニーズに合ったパッケージを探してください。新しいディストリビューションのインストール方法については、v1.0 移行ガイドもご参照ください。