Python開発では、環境構築をどれだけ正確かつ素早く再現できるかが、生産性と品質を大きく左右します。
特に、チーム開発や本番環境デプロイでは、必要なパッケージを手作業でインストールするのは現実的ではありません。
そこで登場するのがrequirements.txtによる一括インストールです。
本記事では、作成方法からインストール手順、エラー対処、よく使うコマンド集まで、実務でそのまま使えるレベルで詳しく解説します。
requirements.txtとは
requirements.txtの役割とPython開発で使う理由
Pythonのプロジェクトでは、多くの場合、外部ライブラリ(パッケージ)を利用します。
例えばWeb開発ならFlaskやDjango、データ分析ならNumPyやPandasなどです。
これらを1つずつ手でインストールしていては、プロジェクトを共有したり本番環境に反映したりするときに手間がかかり、ミスも増えてしまいます。
そこでrequirements.txtは、プロジェクトで必要になるPythonパッケージとそのバージョンを一覧で記述しておくための標準的なテキストファイルとして利用されます。
このファイルを共有しておけば、別の開発者やサーバでも、同じパッケージ群を一括インストールできるようになります。
requirements.txtを使う主な目的を、文章で整理しておきます。
まず、環境の再現性を高めることです。
バージョンを指定しておくことで、「自分の環境では動くのに、別の環境では動かない」という「あるあるトラブル」を大幅に減らせます。
次に、セットアップ作業の自動化が挙げられます。
新しい開発メンバーが参加したときでも、コマンド1つで環境を整えられるため、オンボーディングが非常にスムーズになります。
さらに、本番環境やステージング環境でのデプロイ時にも、同じrequirements.txtを用いることで、「開発環境と本番環境の差異」を減らすことができます。
このように、requirements.txtはPython開発における「環境の設計図」という役割を果たしている、と考えると理解しやすいです。
pipとrequirements.txtの関係と基本ルール
Pythonのパッケージ管理では、標準的にpipというツールを使います。
pipは「Python Package Installer」の略で、インターネット上のPyPI(Python Package Index)からパッケージを取得してインストールします。
requirements.txtは、このpipが「まとめてインストールするための指示書」として読み込むファイルです。
開発者は、コマンドラインからpipに対して-r requirements.txtという形でファイルを指定し、pipはその内容を1行ずつ解釈して、該当するパッケージを順にインストールしていきます。
基本的なルールとして、requirements.txtには1行につき1パッケージを記述します。
例えば、次のような形式になります。
requests==2.31.0
numpy>=1.24.0
pandasこの例では、requestsはバージョン2.31.0を固定し、numpyは1.24.0以上の最新版を許容し、pandasはバージョン指定なしで最新がインストールされます。
また、requirements.txt内では#から始まる行はコメントとして扱われ、pipは無視します。
これにより、なぜ特定のバージョンに固定しているのか、という理由をメモしておくことができます。
requirements.txtの作り方と書き方
既存環境からrequirements.txtを自動生成する方法
既に開発中のプロジェクトがあり、そこにインストールされているパッケージをそのままrequirements.txtに落とし込みたい場合は、pip freezeコマンドを使うのが最も簡単です。
pip freezeは、現在の環境にインストールされているパッケージとそのバージョンを一覧表示するコマンドです。
具体的には、プロジェクトの仮想環境を有効化した状態で、次のように実行します。
pip freeze > requirements.txtこのコマンドは、パッケージ一覧を標準出力に表示する代わりに、requirements.txtというファイルにリダイレクトして保存します。
結果として、その環境で使っているパッケージのスナップショットが、そのままrequirements.txtになります。
例えば、次のようなイメージのファイルが生成されます。
certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.7
numpy==1.26.4
pandas==2.2.2
requests==2.31.0
urllib3==2.2.2なお、pip freezeは「本当に必要なもの」だけでなく、その依存関係としてインストールされたものもすべて列挙します。
開発スタイルによっては、自分でインストールしたトップレベルのパッケージだけを手書きで記述することもありますが、再現性を重視するならpip freezeでの完全なスナップショットを採用するケースが多いです。
バージョン指定(==, >=, <=)の書き方と注意点
requirements.txtでは、単にパッケージ名だけを書くのではなく、バージョン指定も併せて行うことができます。
バージョン指定は環境の再現性に直結するため、「どの記号を使うか」を理解しておくことが重要です。
代表的な指定方法と意味を文章で整理します。
まず、==は、特定バージョンに完全固定する指定です。
たとえばrequests==2.31.0と書くと、必ず2.31.0がインストールされます。
再現性を最大限高められる一方、新しいバージョンが出ても自動では更新されないため、定期的なメンテナンスが必要です。
次に、>=は、指定したバージョン以上であればどれでもよい、という指定です。
numpy>=1.24.0と書くと、1.24.0以上の最新版がインストールされます。
互換性に自信があるライブラリでは便利ですが、マイナーバージョンアップに伴う仕様変更で問題が起こる可能性もあるため注意が必要です。
同様に、<=は、指定したバージョン以下を許容する指定です。
めったに使われませんが、「2.0.0までは動作確認しているが、それ以上は未知」というケースで使うことがあります。
他にも、!=で特定バージョンを除外したり、~=で同一マイナーバージョン内に制限したりする書き方があります。
例えばDjango~=4.2.0とすると、4.2.xの範囲に限定されるため、メジャーバージョンアップによる大きな仕様変更を避けられます。
注意点として、本番環境ではなるべく==か~=で明示的にバージョンを固定することが推奨されます。
開発中に「>=」で指定していた場合でも、リリース時には一度pip freezeなどで実際のバージョンを確定させ、その値で固定しておくと安心です。
開発用(dev)と本番用(prod)のrequirements分割パターン
実務においては、requirements.txtを1つにまとめるのではなく、用途ごとに複数のファイルに分割するケースが多くあります。
特に、開発環境でのみ使うツール(テストフレームワーク、リンタ、フォーマッタなど)と、本番環境でも必要なパッケージを分けて管理すると、本番環境をシンプルかつ軽量に保つことができます。
よく見られるパターンとして、次のような構成があります。
requirements.txt: 本番環境でも必要な共通パッケージrequirements-dev.txt: 開発専用パッケージ(テストや開発支援ツールなど)
例えば、requirements.txtにはDjangoやRequestsなど「アプリケーション実行に必須のもの」だけを記述し、requirements-dev.txtにはpytestやblack、mypyといった開発支援ツールを記述します。
さらに一歩進んだパターンとして、base.txt、dev.txt、prod.txtのように、ベースとなる共通定義と環境ごとの差分定義に分ける方法もあります。
devやprodのファイルの中で-r base.txtと書いて、別ファイルの内容を取り込むことも可能です。
このような分割を行うことで、本番環境では最小限のパッケージだけをインストールし、セキュリティとメンテナンス性を高めることができます。
一方で開発環境では、追加のツール類を含めた豊富な環境を構築できるため、快適な開発体験と安全な本番運用の両立が図れます。
requirements.txtで一括インストールする基本手順
仮想環境(venv)の作成と有効化の手順
requirements.txtによる一括インストールを正しく運用するには、仮想環境(venv)の利用がほぼ必須といえます。
仮想環境とは、1台のPCの中にプロジェクトごとに独立したPython環境を作る仕組みで、パッケージのバージョンや構成をプロジェクト単位で管理できます。
Python 3.3以降では、標準ライブラリのvenvモジュールで仮想環境を作成できます。
ここでは、代表的なコマンドを例示します。
仮想環境の作成
# プロジェクトフォルダに移動
cd my_project
# "venv" という名前の仮想環境を作成
python -m venv venvこのコマンドを実行すると、プロジェクトフォルダ内にvenvというディレクトリが作成され、その中に独立したPythonインタプリタとpipが用意されます。
仮想環境の有効化(Windows)
# PowerShellの場合
.\venv\Scripts\Activate.ps1
# コマンドプロンプトの場合
venv\Scripts\activate有効化に成功すると、プロンプトの先頭に(venv)のように仮想環境名が表示され、以降のpipやpythonコマンドはこの環境のものが使われます。
仮想環境の有効化(macOS / Linux)
source venv/bin/activateこちらも同様に、プロンプトに(venv)が表示されます。
仮想環境を抜けたいときは、OSに関係なくdeactivateコマンドで無効化します。
deactivatevenvを用いることで、プロジェクトごとに異なるバージョンのパッケージを共存させることが可能になり、他プロジェクトへの影響を心配せずにインストールやアップグレードを行えます。
requirements.txtから一括インストールするpipコマンド
仮想環境を有効化したら、いよいよrequirements.txtを使ってパッケージを一括インストールしていきます。
使用するコマンドは非常にシンプルで、次の1行だけです。
pip install -r requirements.txt-rオプションは、pipに対して「このファイルを読み込み、その内容に従ってインストールしてほしい」という意味を持ちます。
pipはファイルの各行を順に解釈し、まだインストールされていないパッケージがあれば、自動的にPyPIからダウンロードしてインストールします。
複数のrequirementsファイルを使っている場合は、それぞれを指定して実行します。
# 本番向けのみ
pip install -r requirements.txt
# 開発向けも含めてすべて
pip install -r requirements.txt -r requirements-dev.txtこの方法を用いれば、新しい開発者がプロジェクトに参加した場合でも、仮想環境を作ってこのコマンドを実行するだけで、ほぼ同じ環境を再現することができます。
一括インストール時のエラー対処
requirements.txtからの一括インストールは便利ですが、状況によってはエラーが発生することがあります。
ここでは、よくあるパターンと対処の考え方を簡単に整理します。
まず、ネットワーク関連のエラーがあります。
PyPIに接続できない場合や、社内プロキシの設定が必要な環境では、「ConnectionError」や「Timeout」といったメッセージが表示されることがあります。
この場合は、ネットワーク設定やプロキシ設定を確認し、必要であればpip install --proxyオプションなども検討します。
次に多いのが、ビルドが必要なパッケージでのコンパイルエラーです。
特に、C拡張を含むパッケージでは、OSに応じたビルドツール(例えばWindowsなら「Build Tools for Visual Studio」、Linuxならbuild-essentialなど)が必要になるケースがあります。
エラーメッセージに「error: Microsoft Visual C++ 14.0 or greater is required」などと出ている場合は、ビルド環境を用意した上で再インストールを試みます。
さらに、バージョン競合もよくある問題です。
pipはなるべく整合的な組み合わせを探しますが、あるパッケージAが「B>=1.0,<2.0」を要求し、別のパッケージCが「B>=2.0」を要求しているような場合、両方の条件を満たせずエラーになります。
この場合、要求しているパッケージ側のバージョンを調整する、あるいはより新しいバージョンにアップグレードするなどの対応が必要です。
エラーが出たときは、まずエラーメッセージの最下部付近をよく読み、「どのパッケージで」「どのような理由で」失敗しているのかを特定することが重要です。
その上で、原因に応じて環境設定の見直しやrequirements.txtのバージョン調整を行うと、スムーズに解決しやすくなります。
よく使うrequirements.txt関連コマンド集
パッケージ一覧を出力するpip freezeの使い方
pip freezeは、requirements.txtとの相性が非常に良いコマンドです。
既に紹介した通り、現在インストールされているパッケージとそのバージョンを一覧表示するため、環境のスナップショット取得に役立ちます。
基本的な使い方は次の2通りです。
# 標準出力に一覧を表示
pip freeze
# ファイルに保存
pip freeze > requirements.txt標準出力に表示させる使い方は、一時的に確認したいときに便利です。
ファイルに保存する場合は、そのまま環境再現に使えるため、「リリース前に現在の環境をrequirements.txtとして固定しておく」といった用途に向いています。
requirements.txtを更新・再生成するコマンド
開発を進める中で、新しいパッケージを追加インストールしたり、バージョンをアップグレードしたりすることは頻繁に発生します。
そのたびにrequirements.txtも更新しておかないと、「ファイルと実際の環境が食い違う」状態になってしまいます。
最もシンプルな更新方法は、変更後の環境で再度pip freezeを行い、requirements.txtを上書きするやり方です。
# 新しいパッケージをインストール
pip install requests-cache
# 動作確認などを行ったあと、requirements.txtを再生成
pip freeze > requirements.txtこのとき、ファイルの差分をバージョン管理ツール(Gitなど)で確認すると、どのパッケージが新たに追加・変更されたかが分かりやすくなります。
なお、プロジェクトによっては、「手書きでトップレベルのパッケージだけをrequirements.inに書き、pip-toolsなどでrequirements.txtを生成する」という運用もありますが、ここではシンプルなpip freezeベースの方法にとどめます。
特定パッケージだけをアップグレードするコマンド
特定のパッケージだけを最新版にしたい場合は、--upgradeオプションを利用します。
例えば、requestsだけアップグレードしたい場合は、次のように実行します。
pip install --upgrade requestsこのコマンドにより、PyPI上で利用可能な最新版のrequestsがインストールされます。
他のパッケージには基本的に影響しませんが、依存関係の都合で一緒にアップグレードされるライブラリもあることには注意が必要です。
アップグレード後は、必ず動作確認を行い、そのうえでpip freezeでrequirements.txtを更新するとよいでしょう。
pip freeze > requirements.txtもし、特定バージョンまでアップグレードしたい場合は、==や~=を用いてバージョンを指定し、requirements.txtに手動で反映する方法もあります。
その際は、チーム内で「なぜこのバージョンに固定しているか」をコメントとして残しておくと、後から見返したときの理解がスムーズになります。
requirements.txtを使った環境再現のベストプラクティス
requirements.txtを活用して環境を再現する際には、いくつかのポイントを押さえておくと、トラブルを防ぎやすくなります。
まず、仮想環境をプロジェクトごとに必ず分けることです。
グローバル環境に直接インストールすると、他のプロジェクトとの衝突や予期せぬバージョン変更が起きやすくなります。
venvを用いてプロジェクト専用環境を作り、その上でrequirements.txtから一括インストールする、という流れを徹底します。
次に、requirements.txtは常に最新状態に保つことです。
新しいパッケージをインストールしたあと、あるいはアップグレードを行ったあとには、pip freezeで再生成し、バージョン管理システムにコミットしておくことで、「誰がいつ、どのライブラリを追加・変更したのか」が履歴として残ります。
また、本番環境では、開発環境と同じrequirements.txtを使うだけでなく、Python本体のバージョンも合わせることが重要です。
Python 3.10と3.11では、同じパッケージでも挙動が変わることがあるため、可能な限り同一バージョンを利用します。
さらに、セキュリティと安定性の観点から、定期的にパッケージのアップデートを検討し、その際にはテスト環境で十分な検証を行ったうえでrequirements.txtに反映する、という運用サイクルを作っておくと安心です。
まとめ
requirements.txtは、Pythonプロジェクトにおける環境構築と再現性確保の中核となるファイルです。
venvによる仮想環境と組み合わせれば、pipコマンド1つで開発環境や本番環境を同じ状態に整えることができます。
この記事で解説した、pip freezeによる自動生成、バージョン指定の考え方、dev/prodの分割パターン、一括インストール時のエラー対処や更新手順を押さえておけば、日常的なPython開発で環境トラブルに悩まされる場面は大きく減るはずです。
