Python 開発において、以下のような課題を感じたことはありませんか？
- プロジェクトごとに異なる Python バージョンを使いたい
- 仮想環境を毎回手動で有効化するのが面倒
-
poetry runを毎回つけるのが煩わしい
これらを一気に解決してくれるのが次の3つのツールです：
✅ pyenv
複数の Python バージョンをインストール・切り替えできるツール。
プロジェクトごとに .python-version を使ってバージョン固定可能。
✅ Poetry
Python のパッケージ管理・ビルド・仮想環境管理を統合したモダンなツール。
依存関係を pyproject.toml で管理し、安定した開発環境を再現できる。
✅ direnv
プロジェクトに入るだけで .envrc に書かれた設定を自動で実行してくれる環境ツール。
仮想環境の自動 activate に最適。
Python プロジェクトで複数バージョンの管理、仮想環境の分離、依存の整合性などを手動でやるのは地味に面倒ですよね。この記事では、Poetry・pyenv・direnv の3つを組み合わせて、「プロジェクトに入るだけで」環境が完全に整う仕組みを構築する手順を解説します。
🎯 この記事で目指すこと
プロジェクトディレクトリに入っただけで...
- 指定した Python バージョン に自動で切り替わる（
pyenv） - Poetry の 仮想環境が自動で有効化される（
direnv） -
.venvが使われていても問題なく連携される
開発者が手作業で source したり poetry run を付けたりする必要をなくします。
Step 1: pyenv の導入と Python のインストール
brew install pyenv
pyenv install 3.10.14
プロジェクトに合わせた Python バージョンを pyenv 経由でインストールしておきましょう。
Step 2: Poetry の設定（仮想環境をローカルに）
Poetry が .venv/ をプロジェクト直下に作ってくれるように設定します。
poetry config virtualenvs.in-project true
Step 3: direnv の導入とシェル設定
brew install direnv
シェル（zsh想定）に hook を追加します。
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc
Step 4: .envrc を作って自動で仮想環境を activate
以下の内容で .envrc を作成します：
echo 'source $(poetry env info --path)/bin/activate' > .envrc
direnv allow
これにより、ディレクトリに入るたびに自動で Poetry の仮想環境が有効化されます。
Step 5: .python-version を指定（pyenv にも教える）
echo "3.10.14" > .python-version
これで cd したときに pyenv が自動で Python 3.10.14 を選択してくれます。
ディレクトリ構成イメージ
my-project/
├── .python-version # pyenv 用
├── .envrc # direnv が読む
├── pyproject.toml # Poetry 管理ファイル
├── poetry.lock
├── .venv/ # Poetry の仮想環境（自動生成）
└── src/ ...
.envrc を Git に含めない場合
echo .envrc >> .gitignore
開発者個人の環境依存ファイルなので、Git 管理から外しておくのが無難です。
まとめ：3ツールの役割とメリット
| ツール | 役割 | メリット |
|---|---|---|
| pyenv | Python バージョン切り替え | プロジェクトごとにバージョンを固定できる |
| Poetry | 依存・仮想環境の管理 | lock ファイルによる再現性の高い環境構築 |
| direnv | 自動 activate
|
手動操作なしで環境が整う快適な開発体験 |
VSCode などと連携したい方へ
VSCode の Python インタプリタを .venv/bin/python に設定すれば、補完・デバッグ・実行すべてが Poetry 環境で動きます。
必要であればその設定方法も別記事で解説します。気になる方はコメントください！
※この記事はGenAIを使って書いております。