どういう記事？

WSL(Ubuntuを使用)で Pyenv × Poetry × PyTorch × GPUの環境を構築している「私の」方法です。
すなわち、深層学習の環境を構築する際に私が使っている環境です。
既にいろいろな方があげてくださっているところではありますし、最適解とも言いにくいですが、2025年現在使っている方法だという点で有用かなと思い、投稿した次第です。

多分、少し変えれば Windows, Mac, 他もろもろでも使えると思います。試していませんが。

この方法の何が素晴らしいか

Windows 特有のエラーが出にくい(WSL2 すごい)
そもそものセットアップが超楽(過去数年間の局所最適解です)
Ubuntu それ自身の環境をほとんど汚染しないはず(pipx ありがとう)
環境ごとに Python Version の細かい指定が可能(pyenv いつもありがとう)
依存関係の問題が起きにくく、確実(poetry ありがとう)
一回作ったら、その後他にも使いまわせる（pyproject.toml を使いまわせば良い）
PyTorch の導入が楽(GPU版も含めて)(poetry ありがとう)
自身のsrc等にPythonのパスを通すのが楽。自身のコードを使うためにsus.path.appendをする必要がない(poetry ありがとう。本来の機能かはさておき)

注意

すみません、WSL環境と、その中のCUDA系の環境までは作っておいてください（気が向いたらそのあたりも書きますが、あまり普段やらないので、いつも試行錯誤しながらやっているんですよね……）

順序

以下の順序で環境を作成します。

PCに対して一回だけ行う処理

pyenv の導入 (数多くの python の version を導入するためのツール)
pipx の導入 (pip ツールをインストールするためのツール)
poetry 環境の導入 (仮想環境を共有するツール)
そのほかの導入

各環境ごとに行う処理

使う環境のルートフォルダにいることを前提とします。
pyenv で python の version を設定した上で、poetry で環境を構築する。

(必要に応じて) pyenv install {使いたいversion}
pyenv local {使いたいversion}
pyproject.toml を準備(私のテンプレートに毛を生やせばいいはずです)
poetry install
使用するライブラリをそれぞれインストールする

手順

PC に対して一回だけ行う処理と各環境ごとに行う処理を順々に用意します。

PC に対して一回だけ行う処理

一回作ってしまえばあとは怖くありません。

pyenv の導入

すみません、書くのが面倒なので他の人の記事を参考にしてください。確立された方法なので、そこまで手間取りませんし、手間取ったとしてもこの処理は PC ごとに一回だけなので許しましょう。

pipx の導入、poetry の導入

欲しいのはpoetryだけなのですが、そのために pipx を入れる方法が楽で、かつ公式( https://python-poetry.org/docs )の推奨するところでもあります。

なお、昔は poetry を入れる際には git から直接入れたり wget 経由で install.sh などの方法を行っていました。今でもその方法はネットに転がっており、実際可能ではあるのですが、現在その方法は公式に推奨されていません（下記、公式の抜粋）

The install-poetry.py installer has been deprecated and removed from the Poetry repository. Please migrate from the in-tree version to the standalone version described above.

公式のいうとおり、pipx を使いましょう。pipx 自体は素晴らしいものなので、入れて損はありません。

$ sudo apt update
$ sudo apt install pipx
$ pipx ensurepath
# ターミナルをリスタートしてねという指示が出るはず。する。
$ pipx install poetry
# 必要に応じて以下を行う。これにより、プロジェクト直下に.venvが生成され、環境がその中に入ってくれるのですっきりする。
# だがしかし WSL で開発を行うとき、私はとある理由でこれを推奨しない。理由はいずれ書く
$ poetry config virtualenvs.in-project true

そのほかの導入

pipx を入れるついでに色々入れるのが楽でいいです。
こんな感じに

$ pipx install tensorboard ...(そのほかコマンドなどを使いたいライブラリ)

pipxで導入することで、PCを汚染することなく、かつ特定の環境に依存することなく、各種ライブラリを使えて便利ですね。

各環境ごとに行う処理

使う環境のルートフォルダにいることを前提とします。無ければ作ってそのフォルダに入ってください。

(必要に応じて) `pyenv install {使いたいversion}`

使いたいバージョン（とくにこだわりや制限がなければ、私はいつも最新のメインversionの一個前（今だと3.11のはず？）のマイナーバージョン最大値を使っています。使用するライブラリによっては特定のversionを要求されたり、versionによってなぜかインストールが進まなくなる、という問題が起きますので、その際は下げるなどしてください。

pyenv local {使いたいversion}

.pyenv_vesion という名前のフォルダが生成されます。

pyproject.toml を準備

本来なら、poetry initを実行後、source等を追加していくのですが、面倒くさいですよね。というわけで、以下が Pytorch で GPU を使う人用の pyproject.toml のテンプレートです。これを環境のルート（現在のパス）に配置してください。
プロジェクト名などは適当に変更してください。あと、gpuを使うかどうか、使う場合に cuda の version はどうか、などで少し変更する箇所があるので、その辺りは適宜変更をしてください。

pyproject.yaml

[tool.poetry]
name = "project_name"  # プロジェクト名
version = "0.1.0"  # バージョンは適当で良い
description = "このプロジェクトの説明を書く"
authors = ["First Last <your.email@example.com>"]
readme = "README.md"  # readmeを書いた場合、該当するファイルが無い場合はエラーになる
packages = [
    # { include = "your_packages", from = "src" },
    # このように書くと、src ディレクトリ以下のモジュールをこの環境の中で使うことができる
    # > from your_packages import your_module
]

[tool.poetry.dependencies]
python = ">=3.11,<3.12"  # 自身のpythonのバージョンを指定する(個人的には最低でも3.10以上を推奨)
# cpu版を使う場合
torch = {version = "^2.3.1+cpu", source = "pytorch_cpu_source"}
torchvision = {version = "^0.18.1+cpu", source = "pytorch_cpu_source"}
torchaudio = {version = "^2.3.1+cpu", source = "pytorch_cpu_source"}
# gpu版を使う場合 (cuda11.8を入れる場合)
# torch = {version = "^2.3.1+cu118", source = "pytorch_cu118_source"}
# torchvision = {version = "^0.18.1+cu118", source = "pytorch_cu118_source"}
# torchaudio = {version = "^2.3.1+cu118", source = "pytorch_cu118_source"}

# 以下に必要なライブラリをどんどん追加
# `poetry add ...`することで、`pyproject.toml`に加筆されていく

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.2"  # 以前私がこれを更新したタイミングの version がこれだっただけで、別にversionは何でもいい。
# devとして入れたい際には、以下のコマンドを使う
# `poetry add --group dev pytest` または `poetry add -G dev pytest`
# 以下に必要なライブラリをどんどん追加

[[tool.poetry.source]]
# sourceを設定することで、pytorchのややこしいinstallを行える
name = "pytorch_cpu_source"  # この名前は任意
url = "https://download.pytorch.org/whl/cpu"
priority = "supplemental"

[[tool.poetry.source]]
# sourceを設定することで、pytorchのややこしいinstallを行える
name = "pytorch_cu118_source"  # この名前は任意
url = "https://download.pytorch.org/whl/cu118"  # cuda version 11.8 用
priority = "supplemental"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

一応、コメントを適当に書きましたが、詳しい説明は LLM に聞いてください。
本当に軽く重要ポイントだけピックアップすると、 source を使うことにより、GPU 版の PyTorch が欲しい場合でも、比較的簡単にインストールできます。

`poetry install`

poetry installをすると、とりあえず環境が構築できます。poetry.lockができて依存関係もちゃんと書いてくれます。
なおエラーが出た場合も、体感ですと8割はそこに書かれているエラー内容を読めば解決できます。後の2割は私には太刀打ちできません……

使用するライブラリをそれぞれインストールする

当然、他にもほしいライブラリがあるはずです。その時は以下のコマンドを使います。

$ poetry add {欲しいライブラリ}

詳しい説明はほかの人に任せますが、pipとほとんど同じ使い方で、pip install {欲しいライブラリ} を上記の書き方委にすれば体感 9 割はうまくいきます。version 指定の方法などはpoetryの公式を参考にしてください。

環境設定終わり

今回説明した方法が比較的安全かつ簡単にGPU付きのPyTorchを入れる方法だと思います。また、後述する使いまわし方法のおかげで、似たような環境を量産することも可能です。

環境を使いまわす

改めてpyproject.tomlを見ましょう。installしたライブラリ等の情報が記載されているかと思います。
なので、ほかの環境に pyproject.toml を持って行けば、同じような環境をすぐに使えるようになります（ただし、OS等が変わると話が変わることがあるので注意）。自分だけの秘伝の pyproject.toml を作りましょう。

注意点

pyproject.toml, poetry install の順番、および poetry init について

今回の手順のうち poetry のコマンドに関して、先に pyproject.toml を準備して、poetry install をして、そのあとに新たにpoetry add ... を行っていく方法は少し邪道です。このような邪道な方法を行った理由はただ一つ、source を設定するのが面倒だからです。
本来の手順を踏みたい人は、poetry init や poetry new を使いましょう。

各poetryコマンドの --no-cache

cache が意外とディスク容量を食います。私はそこまでキャッシュは要らないで、 poetry のコマンドに --no-cache とつけてキャッシュを保存しないようにしています。ちょっと時間はかかりますが、コーヒーでも飲みながら待ちましょう。

poetry の Group 機能等々

色々ありますが、ここでは省略します。

結局インストールした Python の Path ってどこなの

vscode で Python の編集を行う際などに、Pythonの実行ファイルを指定しないといけないことがあります。ただ、仮に virtualenvs.in-project の設定を行っていない場合、意外と見つけるのは困難です。
そこで、以下の方法で確認すると楽なので紹介しておきます。

# 環境のルートパスに移動
$ poetry shell
# {インストールしたPythonのディレクトリ}/bin/activate が明示的に実行されたような表示が書かれた後、shellに入る。でもshellに入る必要はないので抜ける。
$ exit

もっといい方法があるのかもしれませんが、特にこれで困っていないのでこの方法を使っております。

まとめ

今年もよい Python ライフを送りましょう。

所感

新年ですし初投稿なので、とりあえず環境構築の記事でした。
今年の抱負に記事投稿を掲げましたので、適度に記事投稿をしていきます。

所感 2

rye のほうが新しいと言えば新しいですね。ただ、rye を用いて PyTorch GPU 版をすんなり入れる方法があんまり出てこないので、安定択の Poetry を今も使っています。誰か知っていたら教えてください。新しいと言えば、今年はnumpyのメジャーバージョンが2になりましたが、私はまだ怖くて使えていません。あと、poetry も 2.0 がでたらしいですね。また見てみます。

所感2

cpu 環境と gpu 環境（ただしいずれもUbuntu）で1つのpyproject.tomlを使う方法について心当たりのある人がいれば教えてください。