研究室配布資料：Windows 11 + WSL2 + Ubuntu + pyenv + venv + PyTorch 構築手順

1. この資料の目的

本資料では、Windows 11 上で WSL2 と Ubuntu を導入し、VS Code から Ubuntu 環境に接続しつつ、pyenv で Python を管理し、venv でプロジェクトごとの仮想環境を作成し、その仮想環境内に PyTorch を導入するところまでを案内する。

配布対象は、研究室所属学生・新規参加者・環境を再構築するメンバーを想定する。資料の設計方針は次の 3 点である。

2. 採用方針

• Linux 環境は WSL2 + Ubuntu を用いる。
• Windows 側にインストールする GPU ドライバは NVIDIA の Windows ドライバのみ とする。WSL 内に Linux 用 GPU ドライバは入れない。
• Python 本体は OS 付属版を直接運用せず、pyenv で管理する。
• プロジェクトごとの依存関係は venv で分離する。
• パッケージ導入は原則として 仮想環境内 でのみ行う。
• インストール操作は pip 単独ではなく、原則 python -m pip を使う。
• PyTorch は WSL 上の Ubuntu 仮想環境内 に導入する。

3. 全体の流れ

1. Windows 側で NVIDIA ドライバを確認する
2. VS Code の WSL 関連拡張を導入する
3. WSL2 と Ubuntu を導入する
4. Ubuntu を初期設定する
5. pyenv を導入する
6. 研究室標準の Python バージョンを導入して固定する
7. プロジェクトディレクトリを作成する
8. .venv を作成して有効化する
9. 仮想環境外では pip が動かないよう設定する
10. 仮想環境内に PyTorch を導入する
11. GPU が使えることを確認する

4. 事前確認

5. Windows 側: NVIDIA ドライバ確認

nvidia-smi

6. VS Code の WSL 関連拡張導入

VS Code 本体はすでに Windows 側へ導入済みという前提で進める。ここでは WSL 連携に必要な拡張 を入れ、GUI で Ubuntu 側フォルダへ入る手順 も示す。

6.1 WSL 拡張を入れる

code --install-extension ms-vscode-remote.remote-wsl

6.2 GUI で WSL に接続して Ubuntu 側フォルダを開く

左下に WSL: Ubuntu のような表示が出ていれば、現在の VS Code ウィンドウは WSL 上の Ubuntu に接続されている。

6.3 ターミナルから Ubuntu 側フォルダを開く

mkdir -p ~/workspace
cd ~/workspace
code .

この方法でも同様に、VS Code の左下に WSL: Ubuntu の表示が出ればよい。

6.4 Python 拡張を WSL 側へ入れる

Python 拡張は、Windows 側で入っていても、WSL リモート側に別途入れる必要がある 場合がある。WSL 接続中の VS Code で拡張画面を開き、Install in WSL を押して導入する。

7. WSL2 + Ubuntu の導入

wsl --install -d Ubuntu

wsl --update

wsl --status
wsl -l -v

wsl --set-version Ubuntu 2

8. Ubuntu 初期設定

8.1 パッケージ更新

sudo apt update
sudo apt upgrade -y

8.2 pyenv ビルド依存を入れる

sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git wget ca-certificates \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev

8.3 作業用ディレクトリを作成する

mkdir -p ~/workspace
cd ~/workspace

9. pyenv 導入

9.1 pyenv をインストールする

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

9.2 シェル初期化ファイルへ追記する

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init - bash)"' >> ~/.profile

9.3 反映する

exec "$SHELL"

9.4 動作確認

pyenv --version
which pyenv

10. Python 導入とバージョン固定

研究室で Python のバージョンを統一しておくと、依存関係の差異を減らせる。本資料では、研究室推奨 Python を 3.12 系の最新パッチ版 とし、現時点では Python 3.12.13 を使う。

export PYTHON_VERSION=3.12.13
pyenv install $PYTHON_VERSION

mkdir -p ~/workspace/pytorch-env
cd ~/workspace/pytorch-env

pyenv local $PYTHON_VERSION

python --version
pyenv version
cat .python-version

pyenv local により、そのディレクトリ配下では指定した Python バージョンが使われる。

11. venv 作成

11.1 仮想環境を作成する

cd ~/workspace/pytorch-env
python -m venv .venv

11.2 仮想環境を有効化する

source .venv/bin/activate

11.3 基本確認

which python
python --version
python -m pip --version

12. 仮想環境外で pip を止める

研究室内での環境汚染を避けるため、仮想環境を有効化していない状態では pip 系の操作を禁止 する。

12.1 pip 設定ファイルを作成する

mkdir -p ~/.config/pip

cat <<'EOF' > ~/.config/pip/pip.conf
[global]
require-virtualenv = true
EOF

12.2 仮想環境の中では通常どおり使えることを確認する

source ~/workspace/pytorch-env/.venv/bin/activate
python -m pip install --upgrade pip setuptools wheel

12.3 仮想環境の外では止まることを確認する

deactivate
cd ~/workspace/pytorch-env
python -m pip install numpy

12.4 続きの作業のため、仮想環境を再度有効化する

source ~/workspace/pytorch-env/.venv/bin/activate

13. PyTorch 導入

13.1 Ubuntu から GPU が見えることを確認する

nvidia-smi

GPU 名が表示されればよい。WSL 上の nvidia-smi は制限付き表示になる場合があるが、GPU が見えていれば問題ない。

13.2 PyTorch のインストールコマンドを決める

PyTorch は、公式のインストールページから Stable / Linux / Pip / Python / CUDA を選び、表示されたコマンドをそのまま使う。研究室資料として配布する場合は、その時点で採用する CUDA 系列を決めて、次のブロックへ固定値を入れておくとよい。

python -m pip install torch torchvision torchaudio --index-url <ここに研究で採用する PyTorch の公式 index-url を入れる>

13.3 例:CUDA 12.6を使用する場合

pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu126

14. 動作確認

14.1 バージョン確認

python -c "import torch; print(torch.__version__)"

14.2 GPU 利用可否の確認

python -c "import torch; print(torch.cuda.is_available())"

14.3 デバイス名まで確認する

python -c "import torch; print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'GPU unavailable')"

14.4 まとめて確認する

python - <<'PY'
import torch

print("torch version:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("device count:", torch.cuda.device_count())
    print("device name:", torch.cuda.get_device_name(0))
PY

15. よくある問題

15.1 wsl -l -v で VERSION が 1 になっている

wsl --set-version Ubuntu 2

15.2 Ubuntu 側で nvidia-smi が見えない

• Windows 側ドライバが古い、または WSL 対応ドライバが未導入の可能性がある
• wsl --update を実行して WSL を更新する
• Windows を再起動して再確認する

15.3 code . が動かない

• VS Code インストール時に PATH 追加が有効でない可能性がある
• Windows 側から VS Code を起動し、WSL 拡張を導入済みか確認する

15.4 pyenv install が途中で失敗する

• Ubuntu のビルド依存が不足している場合がある
• 先に記載した apt install 群を再確認する

15.5 python -m pip install ... が仮想環境外で失敗する

正常である。require-virtualenv = true を設定しているため、仮想環境外では停止する。

16. 補足: CUDA の複数バージョンを使い分ける

この補足は、PyTorch の仮想環境を用途ごとに分けたい場合 と、nvcc を使う CUDA 開発や拡張ビルドを行う場合 の両方を想定している。

lsb_release -a

16.1 どの使い分け方を採用するか

16.2 方法 A: 仮想環境ごとに PyTorch wheel を分ける

PyTorch を使うだけなら、まずはこちらを優先する。CUDA の差分を 仮想環境単位 で分離できるため、運用が簡単である。

例: CUDA 11.8 系の仮想環境

mkdir -p ~/workspace/torch-cu118
cd ~/workspace/torch-cu118
pyenv local 3.12.13
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

例: CUDA 12.6 系の仮想環境

mkdir -p ~/workspace/torch-cu126
cd ~/workspace/torch-cu126
pyenv local 3.12.13
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

16.3 方法 B: Ubuntu 側に CUDA Toolkit を複数入れる

nvcc を使う場合は、WSL 向けの CUDA 手順に従って version-pinned package を入れる。研究室資料では、WSL-Ubuntu 用の公式ページをその時点で再確認 してから配布する運用が安全である。

例: 12.6 と 11.8 を共存させる

sudo apt update
sudo apt install cuda-toolkit-12-6 cuda-toolkit-11-8

上記のコマンドで入らない場合(WSL2-Ubuntuの場合)
CUDA Toolkitのダウンロードページに入り、希望のリリースバージョンを選択後、下の参照画像の選択を行い画像内の出力されたコマンドをコピーしコマンド画面から実行してください。

指定したバージョンが入っているかを確認

ls -d /usr/local/cuda*

例: プロジェクト単位で CUDA 12.6 を使う

cat <<'EOF' > ~/workspace/use-cuda-12.6.sh
export CUDA_HOME=/usr/local/cuda-12.6
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:${LD_LIBRARY_PATH}
nvcc --version
EOF

source ~/workspace/use-cuda-12.6.sh

例: プロジェクト単位で CUDA 11.8 を使う

cat <<'EOF' > ~/workspace/use-cuda-11.8.sh
export CUDA_HOME=/usr/local/cuda-11.8
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:${LD_LIBRARY_PATH}
nvcc --version
EOF

source ~/workspace/use-cuda-11.8.sh

16.4 /usr/local/cuda の向き先を切り替える方法

ビルドスクリプトが /usr/local/cuda を前提にしている場合だけ、シンボリックリンクを切り替える。

sudo ln -sfn /usr/local/cuda-12.6 /usr/local/cuda
ls -l /usr/local/cuda
nvcc --version

sudo ln -sfn /usr/local/cuda-11.8 /usr/local/cuda
ls -l /usr/local/cuda
nvcc --version

17. 参考リンク

• Microsoft Learn: Install WSL
• Microsoft Learn: Get started using VS Code with WSL
• VS Code Docs: Developing in WSL
• VS Code Docs: Extension Marketplace
• pyenv README
• pip configuration
• pip CLI options
• PyTorch Get Started
• Microsoft Learn: Enable NVIDIA CUDA on WSL 2
• NVIDIA CUDA on WSL User Guide
• NVIDIA CUDA Installation Guide for Linux

更新基準日: 2026-04-04。配布前に PyTorch の install selector、NVIDIA ドライバ配布ページ、CUDA Downloads の WSL-Ubuntu 手順は最新状態を再確認すること。