0. 本シリーズについて

このシリーズでは，Pythonによる機械学習を始める人や，もっと効率的に研究開発を行いたい人に向けて，再現性が高く・開発しやすく・すぐに使える環境構築方法を紹介していきます．

もちろん，好きな記事だけつまんで読むのも大歓迎！

目次

【第0回】(初学者OK) 最強の機械学習環境を作る！pyenv × Poetry × Hydra × W&B × PyTorchで始めるMLライフ
【第1回】Windows民の救世主！WSL2でLinux環境を爆速構築 (初学者OK)
【第2回】Python管理に革命を！pyenv × Poetryで快適開発（Windows / Linux 両対応・初学者OK）（←この記事）
【第3回】PyTorchを使った初めてのディープラーニング体験！(初学者OK)
【第4回】もう設定に迷わない！Hydraでパラメータ管理完全攻略（Python 機械学習・初学者OK）
【第5回】神ツールW&Bで訓練の可視化・比較・ログ化が一瞬で（Python 機械学習・初学者OK）
【第6回】誰でもすぐ使える！Hydra × W&B × PyTorchテンプレを配布！(Python 機械学習)

1. この記事でわかること

Pythonのバージョン管理やパッケージ管理の方法．
pyenvとPoetryのインストール方法（Windows版とLinux版）
Poetryの使い方

おねがい

今回の手順でうまくいかなかった箇所や，つまずいたところがあれば，
ぜひコメントなどで共有してもらえると，他の人（筆者含む）の助けにもなります！
自分で調べてみるのも大事ですが，困ったら誰かに頼るのも大切です．

2. そもそもpyenvって？Poetryって？

pyenvとは

一言でいうと，Pythonのバージョン管理ツール．

Pythonには Python3.9 とか Python3.11 とかいくつもバージョンがある．
これを 簡単にインストールしたり切り替えられる のが pyenv

今後開発を進めていくと，特定のバージョン依存のライブラリ が存在したり，GitHubのコードを再現するときに バージョンが指定されてたり するため，簡単に切り替えられるとめっちゃ便利．

Poetryとは

一言でいうと，Pythonのパッケージ管理＆仮想環境作成ツール

numpy とか pandas など，パッケージの依存関係の調整を自動でやってくれます．

そして 仮想環境 をプロジェクトごとに作ってくれます．これがメリット．

Pythonでは，ライブラリは通常「共通の場所（グローバル環境）」にインストールされます．そのため，あるプロジェクトで不要になったライブラリを消すと，それを使っていた別のプロジェクトが動かなくなります．

Poetryは 仮想環境を自動で作ってくれる ので，各プロジェクトが独立して動き，ライブラリの衝突や巻き添え事故を防げます．

3. イメージ図

各プロジェクトごとに Poetry で仮想環境を作成して，その環境内のPythonバージョンを pyenv が管理するというイメージを図にしました．

4. pyenvのインストール

Windowsに入れたい人と，Linux（WSL2含む）に入れたい人，両方対応できるように分けて書きます．

4.1 Windowsの場合

PowerShellを管理者として実行

左下のWindowsマークを右クリック →「検索」 → 「PowerShell」と検索 → 「Windows PowerShell」を管理者として実行．

実行ポリシーを一時的に緩める

.ps1ファイルを実行できるように，一時的にポリシーを緩めます．
以下のコマンドを入力．

PowerShell(管理者)

Set-ExecutionPolicy RemoteSigned -Scope Process

すると，

PowerShell(管理者)

実行ポリシーの変更
実行ポリシーは、信頼されていないスクリプトからの保護に役立ちます。実行ポリシーを変更すると、about_Execution_Policies
のヘルプ トピック (https://go.microsoft.com/fwlink/?LinkID=135170)
で説明されているセキュリティ上の危険にさらされる可能性があります。実行ポリシーを変更しますか?
[Y] はい(Y)  [A] すべて続行(A)  [N] いいえ(N)  [L] すべて無視(L)  [S] 中断(S)  [?] ヘルプ (既定値は "N"):

と出てくるので，y と入力すれば完了．

pyenv-winのインストール

以下のコマンドでインストール．

PowerShell(管理者)

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

以下のように表示されれば pyenv のインストールは完了．

    ディレクトリ: C:\Users\User


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2025/05/14     10:14                .pyenv
pyenv-win is successfully installed. You may need to close and reopen your terminal before using it.

インストールできてるか確認

PowerShellを一度閉じて，次はコマンドプロンプトを開き pyenv --version と入力．
以下のように表示されればインストールできてます！（バージョンは異なるかも）

cmd

C:\Users\User>pyenv --version
pyenv 3.1.1

4.2 Linuxの場合（WSL2含む）

依存パッケージのインストール

まずは，bashを使えるターミナルを開きましょう．
WSL2であれば，「Ubuntu」を開いてください．

pyenvインストールに必要なものをあらかじめインストールします．
体感1分以上かかります．

チームでLinuxを使っていて責任者で無いのであれば，sudo apt installを勝手にするのは避けましょう．大体インストールされてると思うのでここは一旦飛ばして，次の作業で躓いたら責任者にインストールしていいか聞きましょう．

bash

sudo apt update
sudo apt install -y build-essential libffi-dev libssl-dev zlib1g-dev liblzma-dev libbz2-dev \
libreadline-dev libsqlite3-dev git libncurses-dev curl make xz-utils tk-dev

pyenvのインストール

以下のコマンドを入力します．

bash

curl -fsSL https://pyenv.run | bash

完了したらパスを通しましょう．

bash

echo '' >> ~/.bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
source ~/.bashrc

（参考）これは何をしてるの？

それぞれのコマンドがやっていることは以下の通りです：

echo '' >> ~/.bashrc
→ 見やすくするための空行追加です（意味は特にありません）．

export PYENV_ROOT="$HOME/.pyenv"
→ pyenvのインストール先ディレクトリを指定しています．

export PATH="$PYENV_ROOT/bin:$PATH"
→ pyenvのコマンド（pyenv installなど）を使えるようにパスを通しています．

eval "$(pyenv init --path)"
→ pyenvでインストールしたPythonを使えるように，シェル起動時の設定を追加しています．

source ~/.bashrc
→ .bashrcに書き込んだ設定を今すぐ反映させます（ターミナルを再起動しなくてもよくなります）．

インストールできてるか確認

そのまま，pyenv -vと入力し，以下のように表示されればOK（バージョンは異なるかも）

bash

user@WinDev2407Eval:~$ pyenv -v
pyenv 2.5.7

4.3. （Win Linux 共通）pyenvでPythonをインストール

コマンドプロンプトか bash で以下のコマンドを入力．

表示されるのは，インストール可能なPythonのバージョンです．
基本的には数字だけが書かれたものを選びます．

cmd or bash

pyenv install --list

今回は，3.11.9 をインストールしましょう．

cmd or bash

pyenv install 3.11.9

インストールができたか確認してみます．
一覧に 3.11.9 があればOK.

cmd or bash

pyenv versions

インストールしたPythonは セット をしなければいけません．
システム全体を通して既定で使うPythonのバージョンは以下のように設定します．
（Poetry のインストールに必要なので以下のコマンドは必ず実行．）

cmd or bash

pyenv global 3.11.9

特定のディレクトリ内だけで使うバージョンは，そのディレクトリ上で 以下のように設定します．これにより，global設定を上書きします．（./projects/sample上のバージョンを設定したいなら，cd で ./projects/sample に移動してから実行しよう．）

cmd or bash

pyenv local 3.11.9

最後にPythonが使えるか確認しましょう．
以下のコマンドを入力して，Python 3.11.9 と表示されればOK．

cmd or bash

python --version

ここまでで，pyenv の設定は終了です！次は Poetry を設定しましょう．

5. Poetryのインストール

こちらも，Windowsに入れたい人と，Linux（WSL2含む）に入れたい人，両方対応できるように分けて書きます．
詳しい操作は公式ドキュメントへ．

5.1 Windowsの場合

Poetryのインストール

PowerShellを通常で開きましょう．
以下のコマンドだけでインストールできます．

PowerShell

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

Pathを通す

あとは Path を通すだけです．
以下のコマンドを貼り付けてください．

PowerShell

$target = "$env:USERPROFILE\AppData\Roaming\Python\Scripts"
$envPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$envPath;$target", "User")

インストールできてるか確認

今開いているPowerShellを閉じて，次はコマンドプロンプトを開きます．
以下のコマンドを入力して，インストールできてるか確認しましょう．
Poetry (version 2.1.3) などと表示されればOK

cmd

poetry --version

5.2 Linuxの場合（WSL2含む）

Poetryのインストール

以下のコマンドだけでインストールできます．

bash

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

Pathを通す

あとは Path を通すだけです．
以下のコマンドを貼り付けてください．

bash

echo '' >> ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

インストールできてるか確認．

以下のコマンドを入力して，インストールできてるか確認しましょう．
Poetry (version 2.1.3) などと表示されればOK

bash

poetry --version

6. Poetry の使い方

6.1. プロジェクト直下に仮想環境を作るように設定

初期状態では，仮想環境（パッケージが保存される場所）がよくわからないフォルダに作成される．
これだと，いろいろ不都合が起きるので，プロジェクト直下に作成されるように設定しよう．
以下のコマンドを実行

cmd or bash

poetry config virtualenvs.in-project true

6.2. プロジェクトに仮想環境を作る

前回のシリーズから読んでいる方は，VSCodeを起動して ./projects/sample フォルダを開きましょう．その他の方は，お好きなエディタでプロジェクトを作成したいディレクトリに移動してください．

さっそく，Poetry管理のプロジェクトを作成します．以下のコマンドで！

cmd or bash

poetry init

以下に示すように，対話形式で色々設定されていきます．
同じように答えれば基本問題ないです．

cmd or bash

user@WinDev2407Eval:~/projects/sample$ poetry init

This command will guide you through creating your pyproject.toml config.

Package name [sample]:  
Version [0.1.0]:  
Description []:  
Author [None, n to skip]:  n
License []:  
Compatible Python versions [>=3.11]:  

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file

[project]
name = "sample"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = "3.11.9"
dependencies = [
]


[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"


Do you confirm generation? (yes/no) [yes]

何を聞かれてる？

Poetry `init` 対話モード：各項目の説明

項目	意味	例・補足
Package name	パッケージ名（プロジェクト名）	通常はカレントディレクトリ名が初期値
Version	このパッケージのバージョン番号	初期値は `0.1.0`（最小構成）
Description	プロジェクトの説明文	PyPIに公開する場合などに使われる
Author	作者情報（名前形式）	`n` を入力するとスキップ可能
License	使用するライセンス名	例: `MIT`, `Apache-2.0`, 空欄でもOK
Compatible Python versions	対応するPythonバージョンの範囲	例: `>=3.11`, `^3.10`, `>=3.8,<3.12` など
Would you like to define your main dependencies interactively?	本番環境で必要なパッケージをこの場で追加する？	`no` で後から `poetry add` でもOK
Would you like to define your development dependencies interactively?	開発用（テスト・フォーマッタなど）の依存をこの場で追加する？	こちらも `no` で後から `--dev` 付きで追加可能

完了すると，プロジェクト直下に pyproject.toml というファイルが生成されていると思います．

これは，Poetryの設定ファイルだと思っておきましょう．
必要なライブラリやPythonのバージョンなどがまとめて書かれています．

pyproject.toml

[project]
name = "sample"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
]


[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

実際に仮想環境のディレクトリを作るには以下のように入力．

cmd or bash

poetry install --no-root

完了すると，プロジェクト直下に .venv フォルダが作られてると思います．

6.4. 必要なライブラリをインストールする

Pythonに慣れている方は，pip install や conda install を使ってきたと思いますが，Poetryでは，poetry add {ライブラリ名} でインストールできます．
バージョンを指定したいときは，poetry add {ライブラリ名}={バージョン}

例えば，numpy をインストールするには，

cmd or bash

poetry add numpy

すると，pyproject.toml の dependencies に以下のような記載が追加されていると思います．

pyptoject.toml

dependencies = [
    "numpy (>=2.2.5,<3.0.0)"
]

また，初めてライブラリをインストールしたので，新たに poetry.lock が追加されていると思います．
これは，使用するライブラリの正確なバージョンを記録するファイルです．
これのおかげで，他の人がこのプロジェクトを利用するために poetry install をしたときも同じ環境が再現できます．

6.3. VSCodeに `.venv` を認識させる

ここからは，VSCodeで作業する人向けの情報です．

先ほどの .venv を認識させるために VSCode を再起動します．
✕ ボタンで消して，再度開いてもいいですが，その他にも方法があります．
Ctrl + Shift + P を押して コマンドパレット を開きます．
「reload window」と検索して以下の画像の青くなってる箇所を選択しましょう．

これ意外と便利で，作業中に「なんかVSCode君調子悪いな」と思ったらまずはこれをしてみてください．大体治ります．

.py ファイルを扱うときは，Pythonの拡張機能を入れましょう．
VSCode左側の一番下のアイコン (□ が４つあるやつ) を押して，「python」と検索して一番上に出てきたものをインストールします．

できたら，ファイルのアイコンに戻って，sample.py を作成します．
作成したら，以下の画像の矢印先を押してみましょう．

.venv を認識してくれています．これを選択しましょう．
他にも色々出てきていると思いますが，これらは Python を実行できるファイルの一覧となっています．

初心者の方は，Jupyter Notebook (.ipynbファイル) で作業するのが一番覚えやすいです．
プロジェクト直下に sample.ipynb というファイルを作成しましょう．

今，こんな画面になってると思います．右上の「カーネルの選択」を押しましょう．

すると，こんな画面が出てくると思うので必要な拡張機能をインストールしましょう．

数秒待つと，以下の画面になると思うので，「Python 環境」を押しましょう．

.venv を認識してくれています．これを選択しましょう．
他にも色々出てきていると思いますが，これらは Python を実行できるファイルの一覧となっています．

また，.ipynb を操作するには ipykernel というライブラリが必要です．インストールしておきましょう．

poetry add ipykernel

6.4. Pythonを動かしてみる

先ほど作成した sample.py に以下のコードを記述します．

sample.py

import numpy as np

a = np.array([1,2,3])
b = a * 2

print(b)

このファイルを実行するには poetry run python sample.py とターミナルに入力しましょう．

python **.py のみだと大元の pyenv の python が実行されます．
必ず poetry run を先頭に付けましょう！

実行結果

poetry run python sample.py
[2 4 6]

動かせてそうですね．

sample.ipynb も動かしてみましょう．
VSCodeで .ipynb を動かすときは色々機能がありますが，使っていれば大体勝手に覚えます！

基本的な使い方はGIFでお見せします．
＋コード で新しいセルを作り，各セルの左側にある▷を押せばセルごとに実行できます．

また，上に表示されている「すべてを実行」はそのままの意味で，上から すべてのセル を実行します．
「再起動」は，変数など，実行したものが すべてリセット されます．

ちなみにセルの実行は，セル内で Ctrl + Enter を押してもできますよ．

7. おわりに

ここまでで，pyenv + Poetry をインストールして Pythonのバージョン・パッケージ管理ができるようになりました！少し長かったと思います．お疲れ様でした．

次回はこちら

【第3回】PyTorchを使った初めてのディープラーニング体験！(初学者OK)

またお会いしましょう！

参考にしたサイト