venv環境の依存関係を丸ごと保存 requirements.txtの作成方法

Pythonのプロジェクトでは、後から同じ環境を再現できるように、使ったライブラリの一覧を1つのファイルにまとめておくのが基本です。

本記事では、仮想環境(venv)の前提から、pip freezeを使ったrequirements.txtの作成まで、初心者向けに丁寧に解説します。

環境の再現性を高め、チームや別PCへの共有をぐっと簡単にしましょう。

requirements.txtとは？初心者向けの基本

requirements.txtは、プロジェクトが依存するPythonライブラリ名とそのバージョンを列挙したテキストファイルです。

例えばrequests==2.32.3のように、ライブラリ名とバージョンを==で固定(ピン留め)して記録します。

これにより、他の人や別のマシンでも同じ組み合わせのライブラリを再現できます。

ライブラリ一覧(依存関係)を1ファイルに保存

requirements.txtには、いわゆる「依存関係」(自分が直接入れたライブラリと、それらが内部で使うライブラリも含む)を1ファイルに保存します。

一般的にはpip freezeコマンドの出力をそのまま保存します。

以下は内容のイメージです。

# requirements.txt の例(コメント行は # で始められます)
numpy==1.26.4
pandas==2.2.2
requests==2.32.3
urllib3==2.2.2
# バージョンは == で固定すると再現性が高まります

「どのバージョンを使っていたか」を固定して残すことが最大のポイントです。

固定せずに>=のように幅を持たせると、時間が経って同じ手順でインストールしても違うバージョンが入る可能性があります。

再現性と共有に便利な理由

• 再現性が高まることが第一の利点です。同じrequirements.txtからインストールすれば、同じ環境が再構築できます。
• 共有が簡単になります。チームメンバーにrequirements.txtを渡すだけで、環境を合わせてもらえます。
• デプロイが安定します。サーバーやCIでも同じ依存バージョンを使えるため、「本番だけ動かない」のようなトラブルを減らせます。

なお、インストールの具体的な方法(pip install -r requirements.txt)は別記事で詳しく扱います。

本稿では「一覧を保存する」ことに集中します。

事前準備: venv(仮想環境)を有効化

requirements.txtは、必ずプロジェクトの仮想環境(venv)から作成します。

グローバル環境で作ると、関係ないライブラリまで記録され、後で不具合の原因になります。

下の表は代表的なOSの有効化コマンドです。

まだ仮想環境が無い場合はpython -m venv .venvで作ってから有効化します。

PowerShellでスクリプト実行ポリシーにより有効化が拒否される場合があります。

その際は管理者権限ではなくユーザー権限でSet-ExecutionPolicy -Scope CurrentUser RemoteSignedを検討してください。

組織のルールに従い、変更の影響を理解した上で実施します。

プロジェクトの仮想環境でpipを使う

「その仮想環境のpip」を確実に使うにはpython -m pipの形が安全です。

以下は環境作成から有効化、インストールの例です。

# macOS/Linux/WSL の例
$ python -m venv .venv                 # 仮想環境を作成(初回のみ)
$ source .venv/bin/activate            # 有効化
(.venv) $ python -m pip install requests  # venv配下のpipでインストール

# Windows PowerShell の例
PS> python -m venv .venv                 # 仮想環境を作成(初回のみ)
PS> .\.venv\Scripts\Activate.ps1         # 有効化
(.venv) PS> python -m pip install requests

有効化できているか簡単チェック

次のいずれかで、「venvのPythonとpipが使われている」ことを確認します。

# 1) pip の実体パスを確認
(.venv) $ pip --version
pip 24.2 from /path/to/project/.venv/lib/python3.12/site-packages/pip (python 3.12)

# 2) どの Python を使っているか
(.venv) $ python -c "import sys; print(sys.executable)"
/path/to/project/.venv/bin/python  # or on Windows: ...\.venv\Scripts\python.exe

# 3) which/where で場所を確認
(.venv) $ which python && which pip   # macOS/Linux
(.venv) C:\> where python && where pip  # Windows

確認用の小さなPythonスクリプトを使って、実行中のPython本体と主要パッケージの有無を出力することもできます。

# check_env.py
# 現在の Python 実行ファイルの場所と、主要パッケージの存在を確認するサンプル

import sys
import importlib.util

def has(mod: str) -> bool:
    return importlib.util.find_spec(mod) is not None

print("Python executable:", sys.executable)
print("Has requests?", has("requests"))
print("Has numpy?", has("numpy"))

# 実行例
# (.venv) $ python check_env.py
Python executable: /path/to/project/.venv/bin/python
Has requests? True
Has numpy? False

作成手順: pip freezeでrequirements.txtを作る

venvを有効化した状態でpip freezeの出力をファイルに保存します。

これだけで現在の依存関係が丸ごと固定されます。

コマンド: pip freeze > requirements.txt

bashやWindowsのコマンドプロンプトでは、リダイレクト演算子>で保存できます。

# macOS/Linux/WSL
(.venv) $ pip freeze > requirements.txt     # 一覧を書き出し
(.venv) $ wc -l requirements.txt            # 行数を確認(例)

:: Windows Command Prompt
(.venv) C:\project> pip freeze > requirements.txt
(.venv) C:\project> type requirements.txt

PowerShellは既定のエンコーディングに差があるため、UTF-8を明示して出力するのが無難です。

# Windows PowerShell/PowerShell 7
(.venv) PS> pip freeze | Out-File -Encoding utf8 requirements.txt
(.venv) PS> Get-Content requirements.txt

出力例(一部抜粋)は次のとおりです。

certifi==2024.7.4
charset-normalizer==3.3.2
idna==3.7
numpy==1.26.4
pandas==2.2.2
requests==2.32.3
urllib3==2.2.2

うまくいかない時はpython -m pip freeze

「pipという名前」が別の場所を指しているトラブルを避けるには、python -m pip freezeを使います。

これなら「今のpythonが持つpip」を確実に呼び出せます。

# macOS/Linux/WSL
(.venv) $ python -m pip freeze > requirements.txt

# Windows (Pythonランチャー経由の例)
(.venv) PS> py -m pip freeze | Out-File -Encoding utf8 requirements.txt

保存場所はプロジェクト直下

保存場所の定番はプロジェクトのルートディレクトリ直下です。

ソースコードやテストと並べて置くと分かりやすく、gitにも含めやすくなります。

myproject/
  ├─ .venv/               # 仮想環境(バージョン管理には含めない)
  ├─ src/
  ├─ tests/
  ├─ requirements.txt     # ここに保存
  └─ README.md

.venvディレクトリは.gitignoreに追加しておくのが一般的です。

仮想環境そのものは共有せず、requirements.txtで再現します。

よくあるつまずきと対処

初心者がつまずきがちなポイントを、原因と解決の両面から整理します。

venv未有効で別環境が出力される

症状として、pip --versionで/usr/local/...やC:\Python...など、.venvとは異なる場所が表示されることがあります。

これはグローバル環境のpipを使ってしまっているサインです。

# 悪い例(グローバル環境を参照している)
$ pip --version
pip 24.2 from /usr/local/lib/python3.12/site-packages/pip (python 3.12)

# 良い例(venvを参照している)
(.venv) $ pip --version
pip 24.2 from /path/to/project/.venv/lib/python3.12/site-packages/pip (python 3.12)

対処はシンプルで、venvを有効化し直してから、あらためてpip freezeを実行します。

うまくいかない場合はpython -m pip freezeを使ってください。

pipが見つからない(コマンドエラー)

pip: command not foundや'pip' は内部コマンドまたは外部コマンド...と表示されたら、次を試します。

• 常にpython -m pipの形式で呼び出す。これが最も確実です。
• Windowsではpy -m pipを使うのも有効です。
• もしpip自体が用意されていない場合は、python -m ensurepip --upgradeで導入を試すか、OSのパッケージマネージャや公式インストーラでPythonとpipを入れ直します。

# 例: pip をモジュール経由で確実に起動
PS> py -m pip --version
pip 24.x from C:\Path\to\.venv\Lib\site-packages\pip (python 3.12)

# 例: ensurepip で pip を用意(状況により使えない環境もあります)
PS> python -m ensurepip --upgrade

企業や学校のPCでは権限やプロキシの制約がある場合があります。

その際は管理者や規定に従ってください。

依存を更新したら再度freezeで上書き

ライブラリを追加・アップグレード・削除した後は、必ずpip freezeを再実行してrequirements.txtを上書きします。

これを忘れると、ファイルの内容が実際の環境とズレるため、他の人が同じ環境を再現できません。

# 依存を変更したあとに再度 freeze
(.venv) $ python -m pip install "requests==2.32.3"
(.venv) $ python -m pip freeze > requirements.txt

補足として、pip freezeは「直接インストールしたライブラリ」だけでなく「その下位の依存(サブ依存)」も含めて固定します。

これは正常な挙動で、環境の再現性を確保する狙いがあります。

まとめ

本記事では、venvを有効化した状態でpip freezeを実行し、その結果をrequirements.txtとしてプロジェクト直下に保存するという基本を解説しました。

特に、仮想環境を必ず使うことと、依存を変更したら都度freezeし直すことが重要です。

これにより、環境の再現性とチーム内の共有が格段にスムーズになります。

次のステップとしては、保存したrequirements.txtからの一括インストール(pip install -r requirements.txt)に進むと良いでしょう。