constraints.txtを使用してPythonの推移依存パッケージを管理する

サイオステクノロジーのひろです。

今回はpython環境の依存関係を管理するrequirements.txtとconstraints.txtについて学んだのでブログにまとめてみます。

事前準備

本記事では、実際に手元の環境にパッケージをインストールして動作を確認していきます。

システム全体のPython環境を汚すことなく、クリーンな環境でインストール内容の確認等を行うために、

venv を使用して仮想環境の中でコマンドを打っています。

# 仮想環境の作成
python -m venv .venv

# 仮想環境の有効化 (Linux/macOS)
source .venv/bin/activate

# 仮想環境の有効化 (Windows)
.venv\Scripts\activate

requirements.txtとは何か

requirements.txtはpipによってインストールされるパッケージのリストを記述したファイルです。

必ずしもこの名前である必要はなく他の名前であっても動作しますが、慣例としてrequirements.txtという名前が一般的に使用されます。

例えば、以下のように記述されたrequirements.txtがあるとします。

pandas==3.0.1

pip install -r requirements.txtというコマンドを使用して、パッケージをインストールすると、pandasの3.0.1がインストールされます。

実際にインストールして、何がインストールされているのか確認してみます。

pip install -r requirements.txt

上記のコマンドで仮想環境へ実際にインストールしてみました。何が実際にインストールされたのか以下のコマンドで確認してみます。

pip list

requirements.txtで指定した通り、pandasの3.0.1がインストールされていることがわかります。

しかし、初期状態からインストールされているpipを除いても、numpyやpython-dateutil、sixといったrequirements.txtに記載していないパッケージがインストールされています。

これらのパッケージは推移依存パッケージと呼ばれ、pandasが依存している、pandasが動作するために必要としているパッケージです。

pipの仕様上、これらの推移依存パッケージのバージョンはpandasが要求するパッケージバージョンの中で最新のものがインストールされます。pip installの仕様についてはこちらの公式ドキュメントからご確認ください。

つまり、requirements.txtでパッケージのバージョンを指定していたとしても、推移依存パッケージのバージョンは固定されておらず、インストールを実行したタイミングで互換性のある最新のバージョンをインストールしてしまうということになります。

ちなみにpandasが要求するパッケージバージョンは2026/4/2時点の公式ドキュメントで確認すると以下のようになっています。(sixはpython-dateutilの推移依存パッケージです。)

依存パッケージのバージョンを固定していたと思ってもこれらの推移依存のパッケージバージョンは固定されていないということに注意が必要です。

例えば、推移依存の最新バージョンに脆弱性があったり、破壊的変更が加えられていた場合、パッケージインストールしたタイミングによって、システムが動作しなくなる可能性や、予期せぬ不具合が起こる可能性があります。

この推移依存パッケージのバージョンを固定することができるのが次の章で説明するconstraints.txt及びpip installの-cオプションです。

constraints.txtと-cオプション

前章で挙げた推移依存パッケージのバージョンが固定されない問題を解決できるのがconstraints.txtです。

例によってconstraints.txtという名前である必要はないですが、一般的にconstraints.txtという名前なのでそのように表現いたします。

constraints.txtはインストールされるパッケージのバージョンに制約を設けることができるファイルです。

例えばrequirements.txtに以下の内容を記述してインストールする場面について考えてみます。

pandas==3.0.1

constraints.txtには以下のように記述したとします。

numpy==1.26.4

pip install時に-cオプションでテキストファイルを指定することで推移依存パッケージのインストールバージョンに制約を設けることができます。

実際にやってみます。

以下のコマンドで仮想環境へインストールを行います。

pip install -r requirements.txt -c constraints.txt

インストール後のパッケージリストを確認します。

numpyの1.26.4がインストールされました。

このようにconstraints.txtによって推移依存パッケージのバージョンの固定が可能になります。

constraints.txtの活用方法

推移依存パッケージのバージョンを固定できることがわかりましたが、１つずつ推移依存を調べて書いていくのは面倒で手間がかかります。

以下のコマンドで、現在インストールされているすべてのパッケージとそのバージョンをconstraints.txtに記述できます。

実際に実行してみます。

pip freeze > constraints.txt

実行した結果、直接依存、推移依存を含めて現在インストールされているすべてのパッケージとそのバージョンが記載されました。

このconstraints.txtを-cオプションで指定することで、いつ誰が環境構築をしても、完全に同じバージョン構成を再現できるようになります。

推移依存の意図しないアップデートを防ぎ、常にクリーンな環境を保てます。

requirements.txtに推移依存も含めてすべてのパッケージをpip freezeするというのも手ですが、constraints.txtを併用すれば、requirements.txtにはプロジェクトで必要なパッケージだけを管理し、推移依存を含めた全体のバージョンはconstraints.txtで管理するという役割分担が可能です。

まとめ

パッケージ管理はpip以外にもpoetryやuv等を使用して行う方法がありますが、今回はpythonの標準機能でパッケージを管理する方法についてまとめました。

今後はpoetryやuvを使用したパッケージ管理についても学んでブログに起こしていきたいと思います。

参考文献

pip installの仕様

• https://pip.pypa.io/en/stable/cli/pip_install/#satisfying-requirements

-cオプションについて

• https://pip.pypa.io/en/stable/cli/pip_install/#options