pyenv × PoetryでPythonのパッケージ管理を効率化！（Windows / Linux 両対応・初心者歓迎）

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

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

### 目次
- [【第0回】初心者歓迎！機械学習の開発環境に迷ったらこれ！Poetry × Hydra × W&B × PyTorchで始めるMLライフ](https://qiita.com/gajitaku/items/48c9b1441ee8fe512c9f)
- [【第1回】WindowsとLinux両方使うならWSL2を使え！ (初心者歓迎)](https://qiita.com/gajitaku/items/8a9fbbf53e9ad2809717)
- 【第2回】pyenv × PoetryでPythonのパッケージ管理を効率化！（Windows / Linux 両対応・初心者歓迎）（ **⬅️この記事** ）
- 【第3回】PyTorchを使った初めてのディープラーニング体験！(初心者歓迎)
- 【第4回】ごちゃごちゃファイルとはサヨナラ！Hydraでパラメータ管理（Python 機械学習・初心者歓迎）
- 【第5回】神ツールW&Bで訓練の可視化・比較・ログ化が一瞬（Python 機械学習・初心者歓迎）
- 【第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` が管理するというイメージを図にしました．

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/8d35c2cb-0415-47b8-99a3-9490cc44ddc5.png)

# 4. pyenvのインストール

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

## 4.1 Windowsの場合

### PowerShellを管理者として実行

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

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

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

```powershell: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: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分以上かかります．

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

```bash: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:bash
curl -fsSL https://pyenv.run | bash
```

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

```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
```

<details><summary>（参考）これは何をしてるの？</summary>

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

`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に書き込んだ設定を今すぐ反映させます（ターミナルを再起動しなくてもよくなります）．
</details>

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

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

```bash: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含む）に入れたい人，両方対応できるように分けて書きます．
詳しい操作は[公式ドキュメント](https://python-poetry.org/docs/#installing-with-the-official-installer)へ．

## 5.1 Windowsの場合

### Poetryのインストール

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

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

### Pathを通す

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

```powershell: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:bash
curl -sSL https://install.python-poetry.org | python3 -
```

### Pathを通す

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

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

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

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

```bash: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]
```

<details><summary>何を聞かれてる？</summary>

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

| 項目 | 意味 | 例・補足 |
|------|------|---------|
| **Package name** | パッケージ名（プロジェクト名） | 通常はカレントディレクトリ名が初期値 |
| **Version** | このパッケージのバージョン番号 | 初期値は `0.1.0`（最小構成） |
| **Description** | プロジェクトの説明文 | PyPIに公開する場合などに使われる |
| **Author** | 作者情報（名前 <email> 形式） | `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` 付きで追加可能 |

</details>

---

完了すると，プロジェクト直下に `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」と検索して以下の画像の青くなってる箇所を選択しましょう．

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/cd84a462-866a-46cc-a304-5aa5022b3051.png)

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

---

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/bf33e8f9-fb5d-4834-bd4c-4651acb17731.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/412d8c01-26d6-4e52-9cd7-ea97e2c3338c.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/6fd8d0b0-cd61-4c30-adb4-dc4e684e2fbe.png)


---

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/2a68e38f-501b-422a-a195-90c1aea27712.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/523cedfb-05ea-4343-a6fa-09413b814f27.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/0d54e2ac-2677-4dbe-b6dc-43872e7dca42.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/896031bb-09c8-42a9-b0cb-0f21df9dbe7e.png)

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

```cmd or bash
poetry add ipykernel
```

## 6.4. Pythonを動かしてみる

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

```py:sample.py
import numpy as np

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

print(b)
```

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

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

```:実行結果
poetry run python sample.py
[2 4 6]
```

動かせてそうですね．

---

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

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

![ipynb使い方.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4077793/9ed393b5-0602-4884-b679-975c9d09499a.gif)

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

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

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

### 次回はこちら

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

またお会いしましょう！

## 参考にしたサイト

https://zenn.dev/is0383kk/articles/09e5fd89cbd30c

https://zenn.dev/hr0t15/articles/8ae3564bde2cce