Linuxでの uv（Pythonパッケージマネージャー）の使い方まとめ

1. uvとは

uv は Astral社（Ruff開発チームも同社）によってRust言語で開発された、超高速なPythonのパッケージマネージャーおよびプロジェクト管理ツールです。

pip, pip-tools, pipx, poetry, pyenv, twine, virtualenvなどの複数のツールを1つに統合したオールインワンのツールとして設計されています。

• 公式サイト: https://docs.astral.sh/uv/
• GitHubリポジトリ: https://github.com/astral-sh/uv
• 開発言語: Rust

主な特徴

2. Linuxへのインストール方法

方法1: 公式インストーラー（推奨）

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

または wget を使う場合：

wget -qO- https://astral.sh/uv/install.sh | sh

注意: インストール後、新しいターミナルウィンドウを開くか source ~/.bashrc / source ~/.zshrc を実行してPATHを反映してください。

方法2: Homebrew経由（Linuxでも利用可能）

brew install uv

方法3: pip経由（Pythonが既に入っている場合）

pip install uv
# または
pipx install uv

インストール後の確認

uv --version
# 例: uv 0.7.x

3. 主なコマンド一覧

4. Linuxでの基本的な使い方

4-1. プロジェクトの作成・初期化

# 新しいプロジェクトを作成
uv init myproject
cd myproject

# 以下が自動生成される:
# pyproject.toml（メタデータ）
# .python-version（Pythonバージョンの指定）
# main.py（starterスクリプト）

4-2. Pythonバージョンの管理

# インストール可能なPythonバージョンの一覧を表示
uv python list

# 特定のバージョンをインストール
uv python install 3.12
uv python install 3.11

# プロジェクトで使用するPythonバージョンを固定
uv python pin 3.12

# .python-versionファイルに書き込まれる

4-3. 仮想環境の作成・アクティベート

# 仮想環境を作成（.venvディレクトリが自動生成）
uv venv

# Linux/macOSでのアクティベーション
source .venv/bin/activate

# パッケージのインストール
pip install flask

# アクティベーション解除
deactivate

省略形: uv run python script.py で仮想環境の自動作成・アクティベートを同時に実行可能。

4-4. パッケージの依存関係管理（uvプロジェクト方式）

# パッケージを追加（pyproject.tomlとuv.lockが自動更新される）
uv add requests
uv add "fastapi>=0.100.0"
uv add "django~=4.2"

# 環境を同期
uv sync

# スクリプトを実行（仮想環境が自動で作成され、依存関係が同期される）
uv run main.py

4-5. pip互換インターフェースの使用

既存の pip ワークフローから移行する場合：

# 単一パッケージのインストール
uv pip install flask

# requirements.txtからのインストール
uv pip install -r requirements.txt

# パッケージのアップグレード
uv pip install --upgrade flask

# インストール済みパッケージの一覧表示
uv pip list

# requirements.txtの生成
uv pip freeze > requirements.txt

# 依存関係の解決（ロックファイル生成）
uv pip compile requirements.txt -o requirements.lock

# ロックファイルに基づいて環境を同期
uv pip install -r requirements.lock

4-6. スクリプトの実行

# 基本的な実行（仮想環境が自動で有効化される）
uv run main.py

# Pythonスクリプトの引数を渡す
uv run python script.py --arg value
# または
uv run main.py arg1 arg2

# 異なるPythonバージョンを指定して実行
uv run --python 3.11 main.py

5. uvプロジェクトでの典型的なワークフロー（Linux）

# 1. プロジェクト作成
uv init myproject
cd myproject

# 2. パッケージ追加
uv add requests beautifulsoup4

# 3. 環境の同期
uv sync

# 4. スクリプト実行（仮想環境が自動で有効化される）
uv run main.py

# 5. 依存関係を更新したい場合
uv add "requests>=2.31.0"
uv sync     # uv.lockを更新して環境を再同期

# 6. 別の環境へエクスポート
uv export > requirements.txt

6. メインコマンドの詳しい解説

uv init — プロジェクト作成

uv init myproject       # プロジェクト作成
cd myproject

以下のファイルが自動生成されます：
– pyproject.toml — PEP 621準拠のプロジェクトメタデータ
– .python-version — プロジェクトのPythonバージョン指定
– main.py — starterスクリプト

uv add — 依存関係の追加

uv add requests                         # 単一パッケージ
uv add "fastapi>=0.100.0"               # バージョン指定
uv add "django~=4.2"                    # 互換バージョン指定
uv add black pytest --group test        # グループ指定（dev依存）

• pyproject.toml に自動で記録
• uv.lock にロックファイルが生成・保存

uv sync — 環境の同期

uv sync          # uv.lockに基づいて.venvを同期
uv lock          # ロックファイルのみを更新（環境は変更しない）

uv run — コマンド実行

uv run python script.py           # スクリプト実行
uv run pytest                     # テスト実行
uv run --python 3.12 flask run    # 特定のPythonバージョンで実行

• 仮想環境がなければ自動作成
• uv.lock の更新があれば自動同期

uv python — Pythonバージョン管理

uv python list                    # インストール済み/利用可能な一覧
uv python install 3.12            # 特定バージョンをインストール
uv python pin 3.12                # プロジェクトでの使用バージョンを固定
uv python find ">=3.10,<3.13"    # 条件に合うPythonを検索

uv pip — pip互換インターフェース

uv pip compile requirements.txt -o requirements.lock   # 依存関係解決+ロック
uv pip install -r requirements.lock                    # ロックから環境を作成
uv pip sync requirements.txt                           # 環境をrequirements.txtに同期

uv venv — 仮想環境作成

uv venv                         # .venvディレクトリに仮想環境を作成
uv venv --python 3.11           # 特定Pythonバージョンで仮想環境を作成
source .venv/bin/activate       # Linuxでのアクティベート

7. メインコマンド（追加・まとめ）

uv add — 依存関係の追加（追加）

uv add requests                         # 単一パッケージ
uv add "fastapi>=0.100.0"               # バージョン指定
uv add "django~=4.2"                    # 互換バージョン指定
uv add black pytest --group test        # グループ指定（dev依存）

• pyproject.toml に自動で記録
• uv.lock にロックファイルが生成・保存

uv sync — 環境の同期

uv sync          # uv.lockに基づいて.venvを同期
uv lock          # ロックファイルのみを更新（環境は変更しない）

uv run — コマンド実行

uv run python script.py           # スクリプト実行
uv run pytest                     # テスト実行
uv run --python 3.12 flask run    # 特定のPythonバージョンで実行

• 仮想環境がなければ自動作成
• uv.lock の更新があれば自動同期

8. uvのディレクトリ構造（Linux）

9. Linux特有の設定・注意点

Shell completion（自動補完）

# Bash
uv generate-shell-completion bash > /etc/bash_completion.d/uv

# Zsh
uv generate-shell-completion zsh > ~/.zsh/_uv
source ~/.zsh/_uv

パッケージ管理ツールでのインストール

# Ubuntu/Debian apt経由（公式リポジトリが利用可能な場合）
sudo apt install uv

# Fedora
sudo dnf install uv

推奨: 公式インストーラーによるスタンドアロンバイナリの導入が最も確実です。パッケージマネージャー経由はバージョンが古い可能性があります。

10. pip/poetry/etc. との比較

11. Dockerでの活用例

FROM python:3.12-slim
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN /root/.local/bin/uv sync --frozen --no-install-project
COPY . .
RUN /root/.local/bin/uv sync --frozen
CMD ["/root/.local/bin/uv", "run", "python", "main.py"]

12. まとめ

uv はRustで実装された超高速のPythonパッケージマネージャーです。Linuxでは公式インストーラー（curl | sh）またはHomebrewで導入可能です。

1つのコマンドで Pythonバージョン管理・仮想環境作成・依存関係解決・スクリプト実行 までを一元化できます。

典型的なワークフローは以下の4ステップです：

uv init          # プロジェクト作成
uv add <pkg>     # パッケージ追加
uv sync          # 環境同期
uv run <script>  # スクリプト実行

pipの代替としてのみならず、Poetryやpyenvなど複数のツールを統合するAll-in-Oneソリューションとして期待されています。

参考URL

• 公式サイト（ドキュメント）: https://docs.astral.sh/uv/
• GitHubリポジトリ: https://github.com/astral-sh/uv
• インストールガイド: https://docs.astral.sh/uv/getting-started/installation/
• CLIコマンドリファレンス: https://docs.astral.sh/uv/reference/cli