Zenn
💡

【#環境構築02】pyenv, poetry, uv を使ってpythonを使っている人の普段のチートシート(ubuntuでの操作)

に公開
Python
pyenv
環境構築
poetry
uv
tech

前提（1度きりのセットアップ）

  • OS: Windows + WSL 2（Ubuntu）/ macOS / Linux
  • Python 本体管理: pyenv
  • 依存 & 仮想環境: Poetry 2.1 + poetry‑plugin‑uv
  • IDE: VS Code（Remote‑WSL / SSH・Python・Jupyter 拡張）
  • 任意: ~/.jupyter/jupyter_notebook_config.py で Chrome 自動起動 & トークン無効化

🧰 まずは、Python 開発を支える三種の神器：pyenv × poetry × uv　とはなにか。

Python プロジェクトで「バージョン管理」「依存解決」「仮想環境構築」をスマートにこなすには、この3つのツールが最強タッグです 🐍🚀

🐍 pyenv

複数バージョンの Python を簡単に切り替えられるツール

  • pyenv install 3.12.2 で任意のバージョンをローカルにインストール
  • pyenv local 3.12.2 によって、プロジェクト単位で Python バージョンを固定
  • python -V で切り替えたバージョンが反映される

💡 グローバル／ローカル切替ができるので、複数プロジェクトをまたいでも安心。

📦 Poetry

パッケージ管理 + 仮想環境の自動生成がひとつに

  • poetry init で pyproject.toml を作成
  • poetry add pandas のように依存パッケージを追加
  • .venv を自動で作成・使用（プロジェクトごとに環境を分離）

🛠 仮想環境の切り替え、依存管理、ビルド、公開まで全部これ1つで！

⚡ uv（by Astral）

Poetry（や今後 pip）の依存解決を“爆速化”する Rust 製エンジン

  • poetry self add poetry-plugin-uv で導入可能
  • poetry install や poetry add が 数倍速に
  • pip、conda、hatch などでも将来統合予定

🚀 依存解決が一瞬で終わるのでもう待たない！

🔗 三種の神器の連携

役割 ツール 説明
Python バージョン管理 pyenv プロジェクトごとに Python を固定
依存管理 & 仮想環境 poetry .venv の自動生成＋依存の宣言・インストール
爆速依存解決 uv Poetry の裏側で Rust による高速処理

🚀 “毎プロジェクト同じ手順で快適環境” チートシート

ステップ コマンド例 & やること Why?
1. ディレクトリ作成 mkdir ~/workspace/myproj && cd $_ プロジェクト用の空フォルダを用意
2. Python を決める pyenv install 3.12.2 (初回のみ)
pyenv local 3.12.2 		.python-version で プロジェクトごとに固定
3. Poetry 初期化 poetry init -n  
または poetry new myproj 		pyproject.toml を生成
4. 依存追加 poetry add pandas jupyter uv で爆速解決 & .venv 自動生成
5. 仮想環境へ入る poetry env activate
（旧流派は poetry shell + shell‑plugin） 		プロンプト (.venv) — すべてのコマンドが専用環境で実行
6. Notebook カーネル登録
（初回のみ） 		python -m ipykernel install --user --name=myproj --display-name "Python (myproj)" VS Code / Jupyter でカーネル選択可
7A. VS Code で開く code . → 左下 Python セレクタで .venv を選択 エディタ派
7B. ブラウザ Jupyter jupyter notebook Notebook 派（Chrome 自動起動設定なら即開く）

👫 clone した側の最短復元

git clone <repo-url> && cd <repo>
pyenv local 3.12.2        # .python-version があれば不要
poetry install            # lock に従い依存＋.venv 構築
poetry env activate       # venv 有効化
code .                    # または jupyter notebook

🆙 Python バージョンを後から上げたいとき

# 1) venv を抜ける
deactivate

# 2) 新バージョンを用意・固定
pyenv install 3.13.0
pyenv local 3.13.0   # .python-version が更新される

# 3) venv 作り直し
poetry env remove $(poetry env list --full-path)
poetry install                    # lock に従い再構築
poetry env activate               # 新 3.13 venv へ

要点

  • pyenv local で Python をプロジェクト単位で固定
  • poetry add / install で 依存 & venv を一元管理
  • poetry env activate で 仮想環境に入る
  • VS Code / Jupyter のカーネルを .venv に合わせる
  • バージョン変更時 は poetry env remove → poetry install で venv を作り直す

これで 「clone → 3 コマンド → 開発開始」 がどのプロジェクトでも再現できます 🐍🚀

🔄 既存プロジェクトに “入り直す” 3 ステップ

# ① プロジェクトのルートへ移動
cd ~/workspace/myproj          # ← 自分のプロジェクト名に合わせる

# ② 仮想環境を有効化
poetry env activate            # 旧派は `poetry shell` でも可

# ③ ツールを起動
code .                         # VS Code
#  └─ Notebook 派なら
# jupyter notebook

✔ ポイント

なにが自動？ しくみ
Python のバージョン選択 cd した時点で .python-version を pyenv が読み取り、そのバージョンに固定
仮想環境の切替 poetry env activate が .venv を検知して自動で有効化
VS Code 側の環境 左下の Python セレクタが .venv になっていれば、そのまま実行可能

つまり 「cd → activate → code .」 の 3 コマンドで、いつでも同じ開発環境に戻れます 🐍✨

Discussion