ローカルでは動くのに、チームメンバーやCIで動かない──こうした「環境の違い」による失敗は実務で頻繁に起きます。この記事では、現場で繰り返さないための実務的な手順と落とし穴を、コマンド例やCI/Dockerのサンプルとともに整理します。まずは「自分の環境が再現できない」ことに悩む読者に寄り添い、実際に手を動かせる形で説明します。
1. なぜ仮想環境と依存管理が必要か（現場の失敗事例）
現場でよくある失敗例を挙げます。どれも依存関係や環境の不一致が原因です。
- パッケージのバージョン違いでテストが落ちる（ローカルは通っているがCIで失敗）
- システムにインストールされたライブラリに依存してしまい、オンボーディングで同じ状態を作れない
- バイナリ依存（numpy, torchなど）のインストールに失敗するが原因が明示されない
対処の基本方針は「環境の切り分け」「依存の明示（できれば固定）」「再現手順の自動化」です。
2. venv + pip + requirements のゼロから手順
まずは最もシンプルで依存が少ない方法です。手順とトラブル対処を示します。
作成・アクティベート
# 仮想環境作成
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1
パッケージのインストールとfreeze
# パッケージをインストール
pip install requests numpy
# 環境を固定するrequirements.txtを作成
pip freeze > requirements.txt
インストール（別環境で再現）
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
よくあるトラブルと対処
- バイナリ依存でpip installが失敗する：wheelが利用できるか確認、必要ならプラットフォームに合うホイールを用意するかDockerで統一する
- pipのバージョン差：依存の解決結果が変わることがあるため、pip自体もアップデートしておく（pip install -U pip）
- requirements.txtが雑多になる：直接pip freezeを共有すると開発時の不要パッケージまで入ることがある。手動で主要依存をrequirements.inで管理し、pip-compileで固定する方法も検討する
3. Poetry入門＋実務ワークフロー
Poetryは依存管理とパッケージングを一元化します。実務では、プロジェクトの移行・ロック・CIでの利用がやりやすくなります。
基本コマンド
# Poetry インストール（例）
# macOS/Linux
curl -sSL https://install.python-poetry.org | python3 -
# プロジェクト初期化
poetry init --name myproject --dependencies requests
# 依存追加
poetry add pandas
# lockfile生成（自動）
poetry lock
# 仮想環境内でコマンド実行
poetry run python -m pip install --upgrade pip
実務ワークフロー（移行例）
既存のrequirements.txtからPoetryへ移行する簡単な手順：
poetry init # 最低限の情報を入力
# requirements.txtのパッケージを手動でpoetry addするか、次のように移行
while read pkg; do poetry add "${pkg%%=*}"; done < requirements.txt
poetry lock
移行後はpyproject.tomlとpoetry.lockをバージョン管理します。
4. Lockfileとピン固定戦略
再現性の鍵はlockfile（poetry.lock / requirements.txt pin）です。開発では柔軟性を残しつつ、本番やCIでは厳密に固定する運用が現実的です。
| 用途 | 開発環境 | CI/本番 |
|---|---|---|
| バージョン指定 | 主にメジャー/マイナーを許容（例: requests^2.31） | lockfileで完全固定（poetry.lock または requirements.txt の厳密ピン） |
| 更新頻度 | 週次〜月次で依存更新をテスト | 承認ワークフロー経由で本番に反映 |
5. CI/CDとローカルで同一環境を保証する方法
代表的な手法は3つ：pipのrequirements、Poetryのexport、Dockerです。どれを選ぶかはチームのスキルやデプロイ方法によります。
GitHub Actionsでの例（venv + requirements）
name: CI (venv)
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install dependencies
run: |
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
- name: Run tests
run: |
source .venv/bin/activate
pytest -q
GitHub Actionsでの例（Poetry）
name: CI (Poetry)
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install Poetry
run: curl -sSL https://install.python-poetry.org | python3 -
- name: Install dependencies
run: |
poetry config virtualenvs.create true
poetry install --no-interaction --no-ansi
- name: Run tests
run: poetry run pytest -q
Docker を使って環境を完全に統一する（ポイント）
Dockerfileのポイントはベースイメージの明示、Pythonバージョン固定、lockfileに基づくインストールです。
FROM python:3.11-slim
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN pip install --no-cache-dir poetry && \
poetry config virtualenvs.create false && \
poetry install --no-root --no-dev
COPY . .
CMD ["python", "-m", "your_module"]
6. 依存性の脆弱性チェック・自動更新
脆弱性検査と依存更新の自動化は運用上重要です。代表的なツールを紹介します。
| 目的 | ツール | 備考 |
|---|---|---|
| 脆弱性検査 | pip-audit | requirements.txtや環境をスキャン。CIで定期実行を推奨 |
| 自動依存更新 | Dependabot / Renovate | pull requestで更新を自動作成。テストと承認フローの整備が必要 |
付録：実践的なコマンド例とテンプレート
以下はそのまま貼って使えるサンプルです。必要に応じてプロジェクト名やpython-versionを置き換えてください。
venv 基本
python -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools wheel
pip install -r requirements.txt
requirements.txt を使ったexport（Poetry → requirements）
# Poetry から要件を export（CIやDockerで使う場合）
poetry export -f requirements.txt --output requirements.txt --without-hashes
GitHub Actions の最低限テンプレート（Poetry + pip-audit）
name: CI
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install Poetry
run: curl -sSL https://install.python-poetry.org | python3 -
- name: Install dependencies
run: |
poetry install --no-interaction
- name: Run tests
run: poetry run pytest -q
- name: Run pip-audit
run: |
poetry export -f requirements.txt --output reqs.txt --without-hashes
pip install pip-audit
pip-audit -r reqs.txt
運用上の注意点とチェックリスト
運用時に見落としがちな点をチェックリストにしました。各項目をチームで確認してください。
| 項目 | 確認ポイント |
|---|---|
| Pythonバージョン管理 | pyproject.tomlやCIでpython-versionを明示し、.python-version（pyenv）やDockerfileで固定 |
| バイナリ依存 | numpy/torchなどはプラットフォームに依存。Dockerかホストで同一環境を用意する計画があるか |
| ネットワーク制限 | 企業ネットワークで外部PyPIがブロックされる場合、社内ミラーの利用やWheel配布を準備 |
| オンボーディングスクリプト | 初回セットアップスクリプト（venv作成、依存インストール、pytest実行）のテンプレートがあるか |
| 依存更新ポリシー | 更新頻度、テスト要件、承認フロー（例：週次で自動PR→ステージングで自動テスト→承認で本番反映） |
読後の次の一歩（具体的なコマンド順）
以下の順で進めると、ローカル→CI→チーム導入までスムーズです。
- ローカルで環境作成
python -m venv .venv source .venv/bin/activate pip install -U pip pip install -r requirements.txt # または poetry install - CIで同一手順を再現（上のGitHub Actionsテンプレートを使う）
- オンボーディングスクリプトを作成してREADMEに追加
# setup.sh の例 python -m venv .venv source .venv/bin/activate pip install -U pip pip install -r requirements.txt pytest -q
まとめ
実務で再現可能なPython環境を作るためには、単にツールを知るだけでなく「運用ルール」「lockfileの扱い」「CI/Dockerでの検証」が重要です。小さく始めるならvenv+pip+requirementsで十分です。チームやパッケージ管理を整理したいならPoetryが有効です。どちらの場合も、lockfileの運用、脆弱性チェック、自動更新のワークフローを設計しておけば、環境に起因するトラブルを大幅に減らせます。
次は：ローカルで環境を作ってCIでテストする、そしてオンボーディング手順を1つ作る。これだけで日常的なトラブルが減ります。必要であれば、あなたのプロジェクトに合わせたテンプレート作成も手伝います。