Zenn
🙆

【#環境構築01】Poetry + pyenv + uv の導入手順（WSL / Ubuntu 編）

に公開
Ubuntu
WSL
pyenv
poetry
uv
tech

⚙️ Poetry + pyenv + uv の導入手順（WSL / Ubuntu 編）

この手順では、あなたの環境と同じく WSL（Ubuntu）上での開発環境構築を前提にしています。

✅ 前提：Ubuntu 上で実行中（WSL2）

Ubuntu にログイン後、以下の手順を順番に実行します。

🐍 ① pyenv のインストール

curl https://pyenv.run | bash

※ すでに .pyenv ディレクトリがある場合は削除する必要があります
例：rm -rf ~/.pyenv

その後 .bashrc に以下を追記します（多くは自動で追加されますが確認推奨）：

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

設定を反映：

source ~/.bashrc

Python をインストール（例：3.12.2）：

pyenv install 3.12.2
pyenv global 3.12.2

📦 ② Poetry のインストール（グローバル）

curl -sSL https://install.python-poetry.org | python3 -

その後、以下を .bashrc に追加して PATH を通します：

export PATH="$HOME/.local/bin:$PATH"

そして反映：

source ~/.bashrc

確認：

poetry --version

⚡ ③ uv プラグインの導入（Poetry を高速化）

poetry self add poetry-plugin-uv

これで poetry install や poetry add が爆速になります 💨
しかし、poetryのversionが1.8~1.9でないと使えないようです。

✅ 対処法（Poetry 2.x でも uv を活用するには？）

🟡 1. uv を手動で使う（Poetry 管理外）

プロジェクト内の .venv を使って、uv を pip 互換として使うだけでもかなり高速です。

▶ 仮想環境を有効化

source .venv/bin/activate
pip install uv

▶ 高速インストールを実行

uv pip install -r requirements.txt

これで uv の恩恵（超高速解決＆インストール）を Poetry とは独立して享受できます。

🟢 2. Poetry 1.9 にダウングレードして uv プラグインを使う

Poetry 1.9 までは uv プラグインが正式対応されていました。

▶ Poetry を 1.9 にインストール

curl -sSL https://install.python-poetry.org | python3 - --version 1.9.0

▶ uv プラグインを追加

poetry self add poetry-plugin-uv

これで poetry install や poetry add の実行が uv によって爆速化されます 💨

💡 最新版の Poetry 2.x では poetry self add の仕様が変わっており、poetry-plugin-uv は現在非対応です。そのため Poetry 1.9 系に切り替えるか、手動で uv を使う運用がベストです。

✅ ④ 動作確認・初期プロジェクト作成例

mkdir ~/workspace/research
cd ~/workspace/research
pyenv local 3.12.2
poetry config virtualenvs.in-project true
poetry init -n
poetry add pandas jupyter
poetry env activate

🧪 ⑤ Jupyter カーネルとして登録（VSCode や Jupyter で選べるように）

python -m ipykernel install --user --name=research --display-name "Python (research)"

これにより、VSCode やブラウザ上の Jupyter Notebook で Python (research) として選べるようになります。

🛠️ ⑥ .venv をプロジェクト直下に作る（おすすめ）

poetry config virtualenvs.in-project true

この設定をしておくと、以降のプロジェクトでも常に .venv がプロジェクト直下に作成されます。VSCode や Jupyter でのカーネル認識もスムーズになります ✅

📄 ⑦ pyproject.toml の役割（Poetry の心臓）

poetry init や poetry add を実行すると、自動で pyproject.toml が生成・更新されます。

これは Python プロジェクトの設定ファイルで、以下を一元管理しています：

  • パッケージ名・バージョン・作者情報など
  • 依存パッケージ一覧（バージョン指定付き）
  • 仮想環境構成やビルド設定（将来的に PyPI へ公開する場合にも対応）
[tool.poetry.dependencies]
python = "^3.12"
pandas = "^2.2.3"
jupyter = "^1.0.0"

手動編集もできますが、基本は poetry add や poetry remove で操作するのが安全です。

🧾 ⑧ .gitignore に .venv/ を追加しよう

仮想環境はプロジェクト内に置くのが便利ですが、Git 管理からは除外すべきです。

.gitignore に以下を追記：

.venv/

これで .venv が Git に含まれなくなり、チーム開発や公開時にも安心です。

Poetry は仮想環境の中身を poetry.lock でロックしてくれるので、.venv 自体を共有する必要はありません。

🔐 ⑨ poetry.lock の役割と requirements.txt との違い

✅ poetry.lock とは？

  • 依存パッケージの 正確なバージョンと構成を記録するファイル
  • チームメンバー間や CI/CD で 完全に同じ環境を再現可能
  • poetry install はこの poetry.lock を元に環境を再構築する

🔁 requirements.txt との違い

項目 poetry.lock requirements.txt
管理方法 自動生成される 手動 or pip freeze
依存の階層 トップ + サブ依存を管理 通常は flat（すべてのパッケージ一覧）
使い方 poetry install pip install -r
精度 より正確・再現性あり 一度 freeze しないとバージョンが不明確

Poetry を使うなら poetry.lock を信じて使えば OK！requirements.txt は不要です。

これで pyenv + poetry + uv による高速・安定・再現性バッチリな Python 環境が整います！🐍🚀

Discussion