Python AI 開発環境の構築方法：公式インストーラ・pyenv・uv・GPU対応

Contents

1 Python のインストールとマルチバージョン管理
2 高速依存解決ツール uv の導入と基本操作
3 GPU 対応 AI ライブラリのインストール
4 軽量 JupyterLab とエディタ環境の構築
- 4.1 JupyterLab のセットアップ手順（uv 使用）
  - 4.1.1 起動スクリプト（run_jupyter.sh）
- 4.2 VS Code と PyCharm Community の推奨設定
5 環境再現性を担保する Git 管理と CI/CD のベストプラクティス
- 5.1 uv.lock と requirements.txt の扱い方
  - 5.1.1 Git にコミットするファイル例
- 5.2 GitHub Actions での自動セットアップ例
6 よくあるトラブルと対処法（FAQ）
7 まとめ

スポンサードリンク

Python のインストールとマルチバージョン管理

Windows で公式インストーラを使う手順

手順	操作内容
1. ダウンロード	https://www.python.org/downloads/windows/ にアクセスし、「Download Python 3.x.x」（2024 年時点では 3.12 系）をクリック。
2. インストーラ起動	`python‑3.x.x‑amd64.exe` を実行。チェックボックス「Add Python to PATH」に必ずチェックし、「Customize installation」 → 「Install for all users」（管理者権限が必要）を選択。
3. 必要なオプション	`pip` のインストールはデフォルトで有効 `tcl/tk and IDLE`、`Python test suite` は不要ならチェック外しでも可
4. インストール完了確認	PowerShell を開き、`python --version` と入力。バージョンが表示されれば成功。
5. 環境変数の最終確認	`echo $Env:Path` で Python のインストールディレクトリ（例：`C:\Program Files\Python312\Scripts`）が PATH に含まれているか確認。含まれていなければ手動で追加： `[Environment]::SetEnvironmentVariable("Path", $Env:Path + ";C:\Program Files\Python312;C:\Program Files\Python312\Scripts", [System.EnvironmentVariableTarget]::Machine)`

ポイント
公式インストーラは Windows の標準的なインストール手順で、システム全体に影響しにくい点がメリットです。

macOS / Linux でのビルドインストール（参考）

macOS：Homebrew が推奨されます。brew install python@3.12
Linux (Ubuntu 系)：sudo apt update && sudo apt install -y build-essential libssl-dev zlib1g-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev の後、ソースから ./configure --enable-optimizations && make -j$(nproc) && sudo make altinstall

注意：Linux 系ディストリビューションは公式パッケージが古いことが多いため、最新版を欲しい場合は pyenv の利用をおすすめします。

pyenv と pyenv‑virtualenv によるバージョン切替と仮想環境作成

対象：macOS、Linux、Windows（WSL または PowerShell 用の pyenv-win）

1. 必要ツールのインストール（macOS / Linux）

# macOS (Homebrew)
brew update &amp;&amp; brew install pyenv openssl readline sqlite3 xz zlib

# Ubuntu 系 (apt)
sudo apt-get update
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
    libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
    libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

# macOS (Homebrew)

brew update && brew install pyenv openssl readline sqlite3 xz zlib

# Ubuntu 系 (apt)

sudo apt-get update

sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \

libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \

libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

2. シェル設定（共通）

# Bash の場合は ~/.bashrc、Zsh の場合は ~/.zshrc に追記
export PYENV_ROOT=&quot;$HOME/.pyenv&quot;
export PATH=&quot;$PYENV_ROOT/bin:$PATH&quot;
eval &quot;$(pyenv init --path)&quot;
eval &quot;$(pyenv virtualenv-init -)&quot;

# Bash の場合は ~/.bashrc、Zsh の場合は ~/.zshrc に追記

export PYENV_ROOT="$HOME/.pyenv"

export PATH="$PYENV_ROOT/bin:$PATH"

eval "$(pyenv init --path)"

eval "$(pyenv virtualenv-init -)"

設定後 source ~/.bashrc（または ~/.zshrc）で反映。

3. Python バージョンの取得とグローバル設定

# 利用可能バージョン一覧を表示
pyenv install --list | grep -E &quot;3\.[0-9]+\.([0-9]+)?$&quot;

# 例: 3.12.1 をインストール
pyenv install 3.12.1

# デフォルト（グローバル）バージョンに設定
pyenv global 3.12.1

# 利用可能バージョン一覧を表示

pyenv install --list | grep -E "3\.[0-9]+\.([0-9]+)?$"

# 例: 3.12.1 をインストール

pyenv install 3.12.1

# デフォルト（グローバル）バージョンに設定

pyenv global 3.12.1

4. プロジェクトごとの仮想環境作成（`pyenv‑virtualenv`）

# 仮想環境名はプロジェクト名で管理すると分かりやすい
pyenv virtualenv 3.12.1 ai_project_env

# プロジェクトディレクトリへ移動してローカル設定
cd ~/work/ai_project
pyenv local ai_project_env   # .python-version が生成される

# 仮想環境名はプロジェクト名で管理すると分かりやすい

pyenv virtualenv 3.12.1 ai_project_env

# プロジェクトディレクトリへ移動してローカル設定

cd ~/work/ai_project

pyenv local ai_project_env # .python-version が生成される

効果
pyenv はシステム Python と完全に分離でき、プロジェクトごとに異なるバージョンや依存関係を安全に切り替えられます。

高速依存解決ツール uv の導入と基本操作

Why uv?
Rust で実装された軽量パッケージマネージャ。pip install に比べて数倍高速、ロックファイル (uv.lock) による再現性が高い点が特徴です。公式ドキュメントは https://docs.astral.sh/uv/ を参照してください。

Windows（PowerShell）でのインストール例

# 1. 最新リリースを取得し、実行スクリプトをダウンロード
Invoke-WebRequest -Uri &quot;https://github.com/astral-sh/uv/releases/latest/download/uv-installer.ps1&quot; -OutFile &quot;$env:TEMP\uv-installer.ps1&quot;

# 2. スクリプトを実行（管理者権限が必要な場合は Run as Administrator）
&amp; &quot;$env:TEMP\uv-installer.ps1&quot;

# 3. uv の実行パスをユーザー環境変数に追加
$uvPath = &quot;$HOME\.local\bin&quot;
[Environment]::SetEnvironmentVariable(&quot;PATH&quot;, $Env:PATH + &quot;;$uvPath&quot;, [System.EnvironmentVariableTarget]::User)

# 4. 設定を反映させる（新しい PowerShell ウィンドウで確認）
uv --version

# 1. 最新リリースを取得し、実行スクリプトをダウンロード

Invoke-WebRequest -Uri "https://github.com/astral-sh/uv/releases/latest/download/uv-installer.ps1" -OutFile "$env:TEMP\uv-installer.ps1"

# 2. スクリプトを実行（管理者権限が必要な場合は Run as Administrator）

& "$env:TEMP\uv-installer.ps1"

# 3. uv の実行パスをユーザー環境変数に追加

$uvPath = "$HOME\.local\bin"

[Environment]::SetEnvironmentVariable("PATH", $Env:PATH + ";$uvPath", [System.EnvironmentVariableTarget]::User)

# 4. 設定を反映させる（新しい PowerShell ウィンドウで確認）

uv --version

ポイント
- インストーラは ~/.local/bin に uv.exe を配置します。手動でパスを通すのが忘れやすいので、上記コマンドで自動設定してください。
- PowerShell の実行ポリシーが Restricted になっている場合は、一時的に Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass を実行してからインストールします。

macOS / Linux（共通）でのインストール例

curl -LsSf https://astral.sh/uv/install.sh | sh
# パスが自動的に ~/.local/bin に追加されます。シェル設定ファイルに以下を追記：
export PATH=&quot;$HOME/.local/bin:$PATH&quot;

curl -LsSf https://astral.sh/uv/install.sh | sh

# パスが自動的に ~/.local/bin に追加されます。シェル設定ファイルに以下を追記：

export PATH="$HOME/.local/bin:$PATH"

主要コマンド一覧（H3）

コマンド	説明
`uv init`	`pyproject.toml` と `uv.lock` の雛形を作成。プロジェクトのルートで実行。
`uv add <pkg>[@<ver>]`	パッケージを依存関係に追加し、ロックファイルを自動更新。例：`uv add numpy==1.26.*`
`uv sync`	`uv.lock` に記載された正確なバージョンで環境を再現。CI での推奨コマンド。
`uv venv <path>`	指定ディレクトリに軽量仮想環境（`venv`）を作成。デフォルトは `.venv`。
`uv export -f requirements.txt > requirements.txt`	`uv.lock` から従来の `requirements.txt` を生成し、pip ユーザーと互換性確保。
`uv self update`	uv 本体を最新バージョンに更新。

GPU 対応 AI ライブラリのインストール

CUDA Toolkit と cuDNN のセットアップ（共通手順）

NVIDIA ドライバ：GPU に対応した公式ドライバ（530 系列以上）をインストールし、再起動。
CUDA Toolkit：https://developer.nvidia.com/cuda-downloads から OS に合わせた CUDA 12.x（2024‑2025 年時点で最新は 12.4）を取得しインストール。
cuDNN：同ページの「cuDNN」タブから 8.9 系列（CUDA 12 用）をダウンロードし、C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x\bin へ展開。

環境変数設定例（Windows PowerShell）

$cuda = &quot;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4&quot;
[Environment]::SetEnvironmentVariable(&quot;CUDA_PATH&quot;, $cuda, [System.EnvironmentVariableTarget]::Machine)
[Environment]::SetEnvironmentVariable(&quot;PATH&quot;, &quot;$Env:Path;$cuda\bin;$cuda\libnvvp&quot;, [System.EnvironmentVariableTarget]::Machine)

$cuda = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4"

[Environment]::SetEnvironmentVariable("CUDA_PATH", $cuda, [System.EnvironmentVariableTarget]::Machine)

[Environment]::SetEnvironmentVariable("PATH", "$Env:Path;$cuda\bin;$cuda\libnvvp", [System.EnvironmentVariableTarget]::Machine)

Linux/macOS では ~/.bashrc に以下を追記：

export CUDA_HOME=/usr/local/cuda-12.4
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

export CUDA_HOME=/usr/local/cuda-12.4

export PATH=$CUDA_HOME/bin:$PATH

export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

uv 経由で PyTorch をインストールする方法

# 仮想環境を作成（例: .venv）
uv venv .venv
source .venv/bin/activate   # Windows は .venv\Scripts\activate

# CUDA 12.4 用の PyTorch ホイールリポジトリを指定してインストール
uv add torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu124

# 仮想環境を作成（例: .venv）

uv venv .venv

source .venv/bin/activate # Windows は .venv\Scripts\activate

# CUDA 12.4 用の PyTorch ホイールリポジトリを指定してインストール

uv add torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu124

確認コマンド

python -c &quot;import torch; print('CUDA available:', torch.cuda.is_available())&quot;

1 2	python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

uv 経由で TensorFlow をインストールする方法

TensorFlow は公式パッケージが CUDA バージョンを自動検出します。以下は 2024‑2025 年時点の最新安定版（2.16 系列）をインストールする例です。

uv add &quot;tensorflow&gt;=2.16,&lt;2.17&quot;

1 2	uv add "tensorflow>=2.16,<2.17"

GPU が認識できているかの確認

python - &lt;&lt;'PY'
import tensorflow as tf
print(&quot;TensorFlow version:&quot;, tf.__version__)
print(&quot;GPUs detected:&quot;, tf.config.list_physical_devices('GPU'))
PY

python - <<'PY'

import tensorflow as tf

print("TensorFlow version:", tf.__version__)

print("GPUs detected:", tf.config.list_physical_devices('GPU'))

軽量 JupyterLab とエディタ環境の構築

JupyterLab のセットアップ手順（uv 使用）

# 1. 仮想環境が有効な状態で uv によるインストール
uv add jupyterlab ipykernel notebook

# 2. カーネルをプロジェクト用に登録
python -m ipykernel install --user --name=ai_env --display-name &quot;AI Env (uv)&quot;

# 1. 仮想環境が有効な状態で uv によるインストール

uv add jupyterlab ipykernel notebook

# 2. カーネルをプロジェクト用に登録

python -m ipykernel install --user --name=ai_env --display-name "AI Env (uv)"

起動スクリプト（`run_jupyter.sh`）

#!/usr/bin/env bash
# 仮想環境の有効化
source .venv/bin/activate   # Windows の場合は .venv\Scripts\activate

# JupyterLab 起動（ポート番号はプロジェクトに合わせて変更可）
jupyter lab --no-browser --port=8888

#!/usr/bin/env bash

# 仮想環境の有効化

source .venv/bin/activate # Windows の場合は .venv\Scripts\activate

# JupyterLab 起動（ポート番号はプロジェクトに合わせて変更可）

jupyter lab --no-browser --port=8888

chmod +x run_jupyter.sh
./run_jupyter.sh

chmod +x run_jupyter.sh

./run_jupyter.sh

ポイント
- uv でインストールした場合、依存関係はロックファイルに完全に記録されるので、チームメンバーが同じ手順を実行すれば環境差異はほぼ無くなります。

VS Code と PyCharm Community の推奨設定

エディタ必須拡張 / 設定

エディタ	必須拡張 / 設定
VS Code	Python（Microsoft） Jupyter Pylance（高速 LSP） `settings.json` 例: `{ "python.venvPath": ".venv", "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python" }`
PyCharm Community	File → Settings → Project → Python Interpreter で `.venv/bin/python`（Windows は `Scripts\python.exe`）を選択 View → Tool Windows → Terminal を開き、仮想環境が自動で有効になるように設定（`activate.ps1` / `activate`）

VS Code

Python（Microsoft）
Jupyter
Pylance（高速 LSP）

settings.json 例:
{ "python.venvPath": ".venv", "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python" }

PyCharm Community

File → Settings → Project → Python Interpreter で .venv/bin/python（Windows は Scripts\python.exe）を選択
View → Tool Windows → Terminal を開き、仮想環境が自動で有効になるように設定（activate.ps1 / activate）

環境再現性を担保する Git 管理と CI/CD のベストプラクティス

uv.lock と requirements.txt の扱い方

ファイル	用途
pyproject.toml	プロジェクトのメタデータ・依存関係の宣言（人が直接編集）
uv.lock	正確なバージョンとハッシュを記録。CI で `uv sync --frozen` を実行すれば必ず同一環境になる
requirements.txt	pip 互換性が必要な外部ユーザー向けにエクスポート（`uv export -f requirements.txt > requirements.txt`）

Git にコミットするファイル例

git init
echo &quot;.venv/&quot; &gt;&gt; .gitignore      # 仮想環境は除外
git add pyproject.toml uv.lock requirements.txt
git commit -m &quot;Add project definition and lock file&quot;

git init

echo ".venv/" >> .gitignore # 仮想環境は除外

git add pyproject.toml uv.lock requirements.txt

git commit -m "Add project definition and lock file"

GitHub Actions での自動セットアップ例

name: CI – Test &amp; Lint

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # uv のインストール
      - name: Install uv
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          echo &quot;$HOME/.local/bin&quot; &gt;&gt; $GITHUB_PATH

      # 依存関係の同期（ロックファイル通り）
      - name: Sync dependencies
        run: uv sync --frozen

      # テスト実行例
      - name: Run pytest
        run: |
          source .venv/bin/activate   # 必要に応じて
          pip install pytest
          pytest

name: CI – Test & Lint

on:

push:

branches: [ main ]

pull_request:

jobs:

build:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

# uv のインストール

- name: Install uv

run: |

curl -LsSf https://astral.sh/uv/install.sh | sh

echo "$HOME/.local/bin" >> $GITHUB_PATH

# 依存関係の同期（ロックファイル通り）

- name: Sync dependencies

run: uv sync --frozen

# テスト実行例

- name: Run pytest