Pythonでrequirements.txtを自動生成する方法｜pip freezeとpipreqsの使い分け

Pythonでアプリケーションを開発する際、避けては通れないのがライブラリの管理です。

プロジェクトを他の環境で実行したり、チームメンバーと共有したりする場合、どのライブラリのどのバージョンを使用しているかを正確に伝える必要があります。

その中心的な役割を担うのがrequirements.txtです。

本記事では、このファイルを効率的に生成・管理する方法について、標準的なpip freezeから、より高度なpipreqs、さらには最新のパッケージ管理ツールまで詳しく解説します。

requirements.txtの役割と重要性

Pythonのプロジェクトにおいて、requirements.txtはプロジェクトが依存している外部パッケージの一覧を記録したテキストファイルです。

このファイルがあることで、新しい環境でもpip install -r requirements.txtというコマンドひとつで環境の再現が可能になります。

もしこのファイルが適切に管理されていないと、開発環境では動作するのに本番環境や他のメンバーのPCでは「ModuleNotFoundError」が発生したり、ライブラリのバージョン差異による予期せぬバグに悩まされたりすることになります。

特に現代のソフトウェア開発では、CI/CD (継続的インテグレーション/継続的デプロイ) のプロセスにおいて、自動的に依存関係をインストールするステップが組み込まれることが一般的であるため、正確なrequirements.txtの生成は不可欠なスキルと言えます。

pip freezeによる標準的な生成方法

Pythonに標準で備わっているパッケージ管理システムであるpipには、現在インストールされているパッケージを一覧表示するfreezeコマンドがあります。

これを利用するのが、最も基本的で広く知られている方法です。

pip freezeの基本的な使い方

ターミナルやコマンドプロンプトで以下のコマンドを実行することで、現在の環境にインストールされているすべてのパッケージとそのバージョンをファイルに書き出すことができます。

# 現在の環境のパッケージ一覧をrequirements.txtに保存
pip freeze > requirements.txt

このコマンドを実行すると、以下のような形式のファイルが生成されます。

numpy==1.26.4
pandas==2.2.1
requests==2.31.0

pip freezeの注意点とデメリット

pip freezeは非常に手軽ですが、いくつかの注意点があります。

最大の問題は、「現在の環境にあるすべてのパッケージを書き出してしまう」という点です。

例えば、プロジェクトとは直接関係のないツール (例: リンターやフォーマッター) をインストールしていた場合、それらもすべて含まれてしまいます。

また、仮想環境 (venv) を使用せずにグローバルな環境でこのコマンドを実行すると、過去にインストールした無関係なライブラリが大量にリストアップされ、「汚れたrequirements.txt」が出来上がってしまいます。

これを防ぐためには、プロジェクトごとに必ず仮想環境を作成し、その中で必要なライブラリだけをインストールする習慣が重要です。

pipreqsによるスマートな生成方法

前述のpip freezeの弱点を克服するためのツールとして非常に人気があるのがpipreqsです。

これは環境そのものを見るのではなく、「ソースコード内のimport文をスキャンして、実際に使われているパッケージだけを抽出する」という仕組みを持っています。

pipreqsのインストールと使用方法

pipreqsは標準ライブラリではないため、まずはインストールを行う必要があります。

# pipreqsのインストール
pip install pipreqs

インストールが完了したら、プロジェクトのルートディレクトリで以下のコマンドを実行します。

# カレントディレクトリをスキャンしてrequirements.txtを生成
pipreqs .

もし既にrequirements.txtが存在しており、それを上書きしたい場合は--forceオプションを追加します。

# 既存のファイルを上書きして生成
pipreqs . --force

pipreqsを使用するメリット

pipreqsを使用する最大のメリットは、プロジェクトに必要な最小限の依存関係だけを記述できることです。

仮想環境を使い分けるのを忘れてしまった場合や、複数のプロジェクトが混在している環境から特定のプロジェクト用の設定ファイルを作りたい場合に非常に威力を発揮します。

また、未使用のパッケージが含まれないため、Dockerイメージの軽量化やデプロイ時間の短縮にも寄与します。

pip freezeとpipreqsの比較

どちらの手法を選択すべきか判断するために、主な違いを以下の表にまとめました。

原則としては、仮想環境を構築した上で pip freeze を使用するのがPythonの標準的な作法ですが、開発の途中から管理を始める場合や、整理されていない環境をクリーンにしたい場合にはpipreqsが最適な選択肢となります。

依存関係管理のベストプラクティス

よりプロフェッショナルな開発現場では、単にファイルを生成するだけでなく、運用を考慮した管理が求められます。

ここでは、現場で役立ついくつかのテクニックを紹介します。

1. 仮想環境 (venv) の徹底活用

Python 3.3以降、標準で利用可能なvenvモジュールを使用することは鉄則です。

プロジェクトごとに独立した環境を作ることで、パッケージの競合を防ぎ、pip freezeの結果を常にクリーンに保つことができます。

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

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

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

2. 開発用と本番用の分離

テストツールやデバッグ用のライブラリは、本番環境には不要です。

このような場合、ファイルを分けて管理することが推奨されます。

• requirements.txt (本番動作に必須なもの)
• requirements-dev.txt (テストツールやLinterなど)

requirements-dev.txtの冒頭に -r requirements.txt と記述することで、共通の依存関係を継承させることも可能です。

3. バージョンの指定方法

requirements.txt内では、バージョンの指定方法にバリエーションを持たせることができます。

本番環境では、予期せぬアップデートによる破損を防ぐため、可能な限り完全一致 (==) で指定すべきです。

# 完全一致（最も安全）
requests==2.31.0

# 指定バージョン以上
pandas>=2.0.0

# 特定のバージョンを除外
numpy!=1.21.0

次世代の管理ツール：Poetryやpip-tools

近年、requirements.txtの手動管理における限界を解決するために、より高度なツールが普及しています。

特にPoetryは、現在のPython開発におけるデファクトスタンダードになりつつあります。

Poetryはpyproject.tomlというファイルで依存関係を管理し、poetry.lockによって推移的な依存関係（ライブラリが依存しているライブラリ）まで完全にロックします。

これにより、pip freezeよりも遥かに厳密で再現性の高い環境構築が可能になります。

また、既存のpipベースのワークフローを維持しつつ、依存関係の解決機能を強化したい場合には、pip-toolsも有力な選択肢です。

pip-compileコマンドを使用することで、人間が読みやすい依存リストから、マシンのための厳密なrequirements.txtを自動生成してくれます。

よくあるトラブルと解決策

ライブラリが不足していると言われる

pipreqsを使用した場合、動的にインポートされるライブラリや、特定のプラグイン形式のパッケージを検知できないことがあります。

その場合は、生成されたファイルに手動で追記を行う必要があります。

OS固有のパッケージが含まれてしまう

pip freezeを実行すると、Windows環境特有のpywin32などが含まれることがあります。

これをそのままLinuxサーバーなどで実行するとエラーになります。

クロスプラットフォームでの動作を想定している場合は、環境依存のパッケージを手動で削除するか、環境ごとにファイルを分ける検討が必要です。

実践：requirements.txtの生成スクリプト例

最後に、開発中に便利な「現在の環境を整理してrequirements.txtを更新する」簡単なワークフローをコードブロックで示します。

# 1. 仮想環境をアクティベート（例：Mac/Linux）
source .venv/bin/activate

# 2. 未使用のパッケージがないか確認するためにpipreqsで一時ファイル作成
pipreqs . --savepath requirements_check.txt

# 3. 現在のインストール済みパッケージをfreeze
pip freeze > requirements_full.txt

# 4. 両者を比較して、必要なものだけをrequirements.txtにまとめる
# (ここでは手動での確認を推奨しますが、自動化する場合は以下のように)
cp requirements_full.txt requirements.txt

# 5. 不要な一時ファイルを削除
rm requirements_check.txt

この手順を踏むことで、「ソースコードで使っているか」と「実際に環境に入っているか」の両面から依存関係をチェックでき、より信頼性の高いファイルを作成できます。

まとめ

Pythonプロジェクトにおいて、requirements.txtはプロジェクトの「設計図」の一部とも言える重要なファイルです。

• 手軽に現在の環境を再現したい場合は、仮想環境下でpip freezeを使用する。
• 環境をクリーンに保ち、コードに基づいた最小構成を作りたい場合はpipreqsを活用する。
• 将来的な保守性や厳密な運用を目指す場合は、Poetryなどのモダンなツールへの移行を検討する。

プロジェクトの規模やフェーズに合わせてこれらの手法を使い分けることで、環境構築のトラブルを未然に防ぎ、スムーズな開発を実現しましょう。

依存関係の管理を制する者は、Python開発を制すると言っても過言ではありません。

正確なツール選択と運用ルールを身につけ、プロフェッショナルなコード管理を目指してください。