【2026年版】Python標準venvからPoetry+pyenv-winへの移行統一プロジェクト

Posted at 2026-02-11

本記事は、Windows環境で Poetry + pyenv-win を導入し、python コマンドの参照先を pyenv管理に統一しつつ、Poetryでプロジェクトごとの .venv を構築できる状態までを ステップバイステップで再現するための手順書2026年版です。
実行中によくある詰まるポイントを記載し、同じ状況でも解決できるようにしています。

0. ゴール（最終状態）

pyenv で複数Python（例：3.10/3.11/3.12）を管理できる
python -V が pyenvの指定したバージョン（例：3.11.9）を返す
poetry が動作する（pipx経由でOK）
Poetryで作成したプロジェクトに .venv が作られ、poetry run python -V が 3.11系になる
（分析用途）Poetryで「プロジェクト自体のパッケージ化」をしない運用ができる（package-mode = false）

0.1 想定読者

python 標準の venv で導入してきた人。いわゆる昔の技術書類で導入していた人
conda 環境から脱却したい人
python 標準の venv やら、VSCode のポップアップ指示に任せてリポジトリの中に .venv がはいっていたり、とにかくごちゃごちゃしてしまっている人
Pythonパッケージを配布するといった特殊な仕事ではなく単にプロジェクト毎にPython環境設計を行っている人

0.2 全体の流れ（最短ルートの見取り図）

最初に現状の python 解決順序（PATH/py ランチャー）を確認します。
次に pipx 経由で poetry を導入してスモークプロジェクト（トライアル用）で動作確認します。
pyenv-win を導入して Python 3.11 をインストールし、python -V が 3.11 を指すように PATH（特にシステム環境変数側の Python312 エントリ）を調整します。
最後に poetry 側で (1) Python 制約を 3.11 互換にし、(2) poetry.lock の整合を取り、(3) 非配布用として package-mode = false を設定して poetry install をエラーなく通す、という順で完成させます。

1. 事前確認（現状把握）

1.1 `python` の解決順序を確認する

PowerShell で以下を実行。

where.exe python
py -0p
python -V
py -V

よくある出力結果

...\AppData\Local\Programs\Python\Python312\python.exe が先頭に来る
...\AppData\Local\Microsoft\WindowsApps\python.exe が見える（最後尾など）

補足：WindowsApps 配下の python.exe
...\Microsoft\ 配下に python.exe が見える状態の人は多くの場合、Microsoft Store の「App Execution Alias（スタブ）」です。最後尾なら実害は少ないが、将来の混乱要因にはなり得ます（必要なら OFF にできますが本記事では記載しません）

2. pipx と Poetry（最小構成で導入）

2.1 pipx インストール（user install）

python -m pip install --user pipx

インストールログで以下のような警告が出ることがあります：

...Python312\Scripts is not on PATH

これは、pipx.exe が置かれたフォルダに PATH が通っていないだけです。次のコマンドを打ちこんでpipxの ensurepath を使いましょう。

python -m pipx ensurepath

その後、ターミナル再起動して確認します。

pipx --version
where.exe pipx

これで pipx のバージョンと pipx の保存先が見えていたら OK です。

2.2 pipx 経由で Poetry を導入

pipx install poetry
poetry --version
where.exe poetry

補足：poetry.exe の置き場が Python312 配下ではないことは正常です
where.exe poetry が C:\Users\<user>\.local\bin\poetry.exe を指すことがあります。
これは pipx の設計上正常です（CLI 入口は .local\bin に置くためです）。
poetry 本体は pipx の仮想環境内に隔離されています。

3. Poetry スモークテスト（.venv 作成と依存導入）

3.1 `.venv` をプロジェクト直下に作る設定

この操作で、poetry の .venv を global ではなく project ベースで作成する動作に設定変更します

poetry config virtualenvs.in-project true
poetry config virtualenvs.prefer-active-python true

3.2 スモークテスト用ディレクトリ作成と初期構築

適当なディレクトリに poetry-smoke という名前のフォルダを作成します。この中で環境構築テストを行います。

cd <適当な場所のディレクトリパス>
mkdir poetry-smoke
cd poetry-smoke

poetry init -n
poetry add requests
poetry run python -V
poetry run python -c "import requests; print(requests.__version__)"

4. pyenv-win 導入（Pythonの参照先を統一する本丸）

4.1 pyenv-win インストール（PowerShell）

pyenv-win の公式HPにも記載されている、以下のコマンドを PowerShell で入力します。

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "$env:TEMP\install-pyenv-win.ps1"
& "$env:TEMP\install-pyenv-win.ps1"

PowerShellを再起動後、インストールがされているかを確認します。

pyenv --version

4.2 インストール可能な Python の一覧を確認

インストール可能な Python の一覧が全部出力されます。ここで自分が今後標準で使いたいPyhtonのバージョン（例えば3.11）が含まれているかを確認します。

pyenv install -l

4.3 Python 3.11 をインストール・指定

ここからは、例としてPython 3.11.9を標準としてインストールする流れで進みます。次のコマンドを打ちます。

pyenv install 3.11.9
pyenv global 3.11.9
pyenv rehash

補足：CPython と PyPy の違い
pyenv install 3.11.9 は CPython 3.11.9 を入れる指示です。
pypy3.11 は PyPy。PyPyを入れたい場合だけ pyenv install pypy3.11-... を明示します。

以下のコマンドを打って pyenv のバージョンが先ほど指定したPython バージョンになっているかを確認します。

pyenv versions
pyenv exec python -V

5. 「pyenv で 3.11 が入ったのに python -V が 3.12 のまま」問題の対処方法

おそらくここまでは、順調に作業は進むと思います。しかしながらこれまでPython を使ってきた人はここで躓くのではないでしょうか。
主な原因は PATH の環境変数の優先順位が pyenv が最上位になっていないからです。これを解決します。

5.1 問題の確認

pyenv exec python -V コマンドでは 3.11.9 になる人（pyenv 自体は正常）
しかし python -V コマンドでは 3.12.10 のままの人

これは PATH 優先順位の問題です。

5.2 試運転（セッション限定で PATH を先頭に挿入）

恒久的な対応を実行する前に、一度だけ「本当に PATH の問題か」を確定します。以下のコマンドは立ち上げている PowerShell 内でのみの Path 操作です。

$env:Path = "$env:USERPROFILE\.pyenv\pyenv-win\shims;$env:USERPROFILE\.pyenv\pyenv-win\bin;$env:Path"
pyenv rehash
python -V
where.exe python

これで python -V が 3.11.9 に変われば、原因は PATH で確定です。

5.3 恒久解（Windows環境変数 Path を修正）

目標

where.exe python の先頭が ...\pyenv-win\shims\python... になること。

手順

Windows の環境変数 PATH を確認

「システム環境変数の変数」と Windows で検索して、環境変数ダイヤログを開きます
上段の「ユーザーの環境変数」の中にある Path を選択して編集ボタン
Path が通っているリスト一覧が見えるので、where.exe python でのリストに該当するものを確認して、Python312/Scripts、Python311/ などといった変数をリスト下位に移動させる（あるいは削除する）
これと同じように下段の「システム環境変数」の中にある Path を選択して編集ボタンを押し、同様の処理をする。

なお、システムとしては優先順位は「システム環境変数」＞「ユーザー環境変数」という位置づけです。システム環境変数に pyenv とは関係がない Python の path が入ってしまっていたなら削除した方が無難です。

環境変数の編集後、PowerShell を全終了→再起動（必要なら PC 再起動）して確認：

where.exe python
python -V
pyenv versions

python -V が 3.11.9 となっていたら pyenv で導入した python を優先的に見ている状況です。

6. Poetry を 3.11 に揃える（Python制約・lock整合）

poetry-smoke には poetry の実行テストとして初期設定をした際に、ディレクトリ内に自動で pyproject.toml が作成されています。つまり poetry を入れたときに紐づいていた Python 3.12 で作られています。これを作り直してそろえる作業を行います。

6.1 現状確認

次のコマンドを打って状態を確認します。コマンドを打つ際は cd を移動して poetry-smoke に移動しておきます。

cd <poetry-smokeのパス>
poetry env info
poetry run python -V

おそらくこのコマンドでは、python のバージョンは poetry を入れたときに紐づいていた Python 3.12 になっていると思います。

6.2 pyproject.tomlの編集

pyproject.toml 内に以下の制約条件が記載されていると思います。これを 3.11 でも通るように緩めます

[project]
requires-python = ">=3.12" # これを ">=3.11" に変更する

6.3 poetry.lock の更新

書き換えた後に、以下のコマンドを打ちます。

poetry env remove --all
poetry env use 3.11
poetry install
poetry run python -V

これを実行すると poetry install の段階で次のエラーがでると思います。

pyproject.toml changed significantly since poetry.lock was last generated. Run 'poetry lock'

これは poetry.lock も 3.12 に準拠しているから 3.11 に変えるんだったら poetry.lock も変更してという意味ですので、次のコマンドを打ちます。

poetry lock
poetry install

6.4 ディレクトリを配布パッケージとして扱わない設定に変更

poetry install 中に次のエラーが出る人がいると思います。

The current project could not be installed: No file/folder found for package ...
If you do not want to install the current project use --no-root ...
... disable package mode by setting package-mode = false ...

これは、ディレクトリを配布パッケージで考えてるのか否かの設定を聞かれています。今回は配布はせずにプロジェクト毎のインストールライブラリの管理をしたいだけです。
したがって、package-mode = false を採用します。毎回 --no-root を付ける運用は「付け忘れ」で再発しやすく、標準化に不向きです。

次の情報を pyproject.toml に記入します。

[tool.poetry]
package-mode = false

このあとに、再度以下のコマンドを実行すると、問題なくインストール完了になります。

poetry install

7. 最終確認

以下のコマンドを入力して期待する返答が返ってくれば、Poetry + pyenv-win の基礎導線は完成です。

7.1 pyenv が python を握っているかどうかを確認

python -V
where.exe python
pyenv versions

期待する返答：

python -V が 3.11.9
where.exe python 先頭が ...\pyenv-win\shims...

7.2 Poetry プロジェクトが 3.11 の .venv で動くかどうかの確認

poetry run python -V
poetry run python -c "import requests; print(requests.__version__)"