UV + Python 環境づくりの手順メモ

今回は、UVとpythonを利用した環境の導入手順メモの忘備録を記録します。

はじめに

UVとは、pythonのパッケージ管理ツールとなります。今回は直接pipコマンドを利用せず、uvコマンドで完結します。

前提環境

• OS: macOS / Linux / WindowsはWSL2上のUbuntu (Windows上に直接インストール無し)
• Python: Python3が1つはインストールされている（なければ後述）

Windows WSL2 Ubuntu 24.04.2 LTSの環境にpython3.10をインストールする前提です。シェルはbashです。

✅ コマンド集

それでは構築していきます。

Pythonインストール

少なくとも一つのバージョンが必要です。

sudo apt install python3.10

uv インストール

pipなしでインストールします。

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

# Check if the uv is successfully installed 
uv --version

uv プロジェクト作成

このコマンドが便利なので使っています。プロジェクトディレクトリと関連ファイルを自動で作成します。

プロジェクトの保存場所にはくれぐれも気を付けてください。依存パッケージをインストールので、仮想環境の(後で作成する).venvフォルダーが巨大になります。

cd /path/to/your_dev_holder
# Use uv to initiate a project with project_name and python version
uv init --python 3.10 project_name

ディレクトリを確認すると以下のようなファイルがプロジェクトディレクトリに作成されます。

ls project_name

.git
.gitignore
.python-version
README.md
main.py
pyproject.toml
uv.lock

• requirements.txtは利用しません
• パイソンのバージョンを.python-versionで指定します
• そのバージョンによって、簡パッケージ管理してくれます

uv 仮想環境作成

uv venvを実行し、.venv環境を作成します。以下実行例です。

cd project_name
uv venv

#» uv venv
# Using CPython 3.10.18
# Creating virtual environment at: .venv
# Activate with: source .venv/bin/activate

# check if .venv exists
ls -al .venv
# .venv

uv 仮想環境の立ち上げ(オプション)

通常のpip venvのワークフローが必要な場合は実行します。基本uvは必要ないです。

# start virtual environment
source source .venv/bin/activate

依存パッケージの記述

pyproject.tomlファイルに設定を追加します。

書き方が分からないや依存パッケージの最新版がわからない場合は、後述する uv add やuv add --dev を利用すべきです。自動で最新の安定版を取得し、uv.lock にも自動反映され、pyproject.toml を自動で書き換えます。

[project]
name = "Your Project Name"
version = "0.1.0"

[tool.uv.dependencies]
torch = "2.3"
torchvision = "*"
torchaudio = "*"
markupsafe = "2.1.5"
setuptools = "*"
pytorch_geometric = "2.5.0"
stable-baselines3 = "2.2.1"
featuretools = "1.31"
xgboost = "2.1"

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

pyproject.tomlファイルを参照に、インストールしてくれます。プロジェクト用と開発用のコマンドが用意されています。但し、uv syncだけで、[tool.uv.dependencies] + [tool.uv.dev-dependencies]両方インストールされます。

uc sync
uv sync --dev	# dev dependencies も含めて同期.　pyproject.tomlに記述

依存パッケージの追加及び削除

依存関係のパッケージを追加/削除します。pyproject.tomlファイルも更新されます。

uv add <package>
uv add --dev <package>

uv remove <package>
uv remove --dev <package>

依存パッケージの更新

依存関係を最新に更新（バージョン範囲内で）。uv updateで[tool.uv.dependencies] + [tool.uv.dev-dependencies]の両方を更新します。

uv update
uv update <package>

# or 

uv update --dev <package> #開発のみの場合

依存パッケージ調査

知っていれば便利かもしれません。

uv search <package> # PyPI 検索
uv info <package>   # パッケージ情報（PyPI）

別途、パッケージ追加 (可能な限り uv add を利用すべき)

パッケージをインストールしてくれます。pyproject.tomlファイルは更新しません。

uv pip install package

uv 環境でのpython実行

uv runで.venvを認識し、pythonを実行してくれます。又はsourceで仮想環境を立ち上げて、pythonを実行します。makefileが便利なので、用意しておきましょう。

uv run python main.py

# or

source .venv/bin/activate 
python python.py

# or 

make run

依存関係ツリーの表示

依存関係を表示してくれます。

uv tree

✅ uv ベストプラクティス

1. 環境初期化：必ず uv init + uv venv

uv init
uv venv

• pyproject.toml と .venv/ を確実に作る
• .venv/ は .gitignore に追加しておく（uv.lock は追加しない）

2. 依存追加は常に uv add を使う

uv add numpy pandas matplotlib
uv add -d black ruff pytest  # 開発用は -d (--dev)

• pyproject.toml に記録される
• uv.lock にバージョンが固定される
• uv pip install は一時利用のみ（記録されない）

3. スクリプト実行は uv run

uv run python main.py

• .venv を自動で使ってくれる
• source .venv/bin/activate は不要
• JupyterもOK → uv run jupyter lab

4. 再現性のあるセットアップは uv sync

uv venv
uv sync --dev

• pyproject.toml + uv.lock から環境を完全再現
• requirements.txt は不要（使いたいなら uv pip freeze で生成可能）

5. 依存関係の更新は uv update / uv upgrade

uv update             # 最新パッチまで更新
uv upgrade            # 最大バージョンまで更新（やりすぎ注意）
uv update pandas      # 指定パッケージだけ更新

6. pyproject.tomlファイル

UVの [tool.uv.dependencies] / [tool.uv.dev-dependencies] を分けると、開発と本番を切り分けやすくなります。

[project]
name = "zerobuilder"
version = "0.1.0"
description = "Zero-shot learning project builder"
requires-python = ">=3.9"

[tool.uv.dependencies]
torch = "2.3"
torchvision = "*"
torchaudio = "*"
pytorch_geometric = "2.5.0"
stable-baselines3 = "2.2.1"
featuretools = "1.31"
xgboost = "2.1"
markupsafe = "2.1.5"
setuptools = "*"

[tool.uv.dev-dependencies]
jupyterlab = "*"
black = "*"
ruff = "*"
pytest = "*"

[tool.black]
line-length = 88
target-version = ['py39']

[tool.ruff]
line-length = 88
select = ["E", "F"]

7. .gitignore に入れるべき項目

• uv lock はコミット必須！なので、ここには入れません。

# Python
__pycache__/
*.pyc
*.pyo
*.pyd
*.ipynb_checkpoints/

# UV / venv
.venv/
.uv/

# VS Code
.vscode/

# Jupyter
.ipynb_checkpoints/

# OS
.DS_Store
Thumbs.db

# Logs
*.log

8. Makefile 例

• ruff, pytestコマンドやスクリプトと組み合わせる

.PHONY: setup run lint format test clean

# 初期セットアップ（環境構築）
setup:
	uv venv
	uv sync --dev

# スクリプト実行
run:
	uv run python main.py

# Linter
lint:
	uv run ruff src/

# フォーマット
format:
	uv run black src/

# テスト
test:
	uv run pytest tests/

# キャッシュ・ビルド削除
clean:
	rm -rf .venv .uv __pycache__ *.pyc .pytest_cache

9. VSCode との統合

WindowsだとCtr + Shift + P でPreference: Open User Settingsを開く(日本語化済みなら基本設定:　設定(JSON)を開く)

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.formatting.provider": "black"
}

10. WSL × UV × .venv でのエラー

💡問題

• .venv/ が Windows側（/mnt/c/...） にあると、uv run python や .venv/bin/python でエラーになることがある
• 例: Exec format error, Permission denied。venv/bin/python の shebang や chmod +x が壊れることがある

✅原因

• .venv/ 内の Python 実行ファイルは Linux バイナリ（WSL用）
• しかし Windowsファイルシステム（NTFS） 上では実行権限が正しく扱えない
• .venv/bin/python の shebang や chmod +x が壊れることがある

✅解決策

• .venv/ は WSL側 (ext4) に作ること
• プロジェクトごと Linux 側へ移動
• uv run を使う
• Windows側のディレクトリで .venv を作らない

終わりに

いかがでしたでしょうか？コメント等あればください。

Happy Hacking!