はじめ方とuvセットアップ

本書の最初の章です。本書全体を貫く 2 つの標準 — Python 3.14 と uv — を先に押さえ、最初のプロジェクトを作るところまで進みます。第2章以降の例コードは、すべて本章で作った環境の上で動きます。

これに続く第5部の運用章(型チェッカ・ロギング・ライブラリ公開・CLI)も、結局は本章で作った pyproject.toml を少しずつ広げていく形でつながります。そのため本章は「1部1章」以上の重みがあります。ゆっくり進めてください。

Python の何が変わったか #

Python は 3.14 までにかなり変わりました。主な変化をいくつか挙げると次の通りです。

• 型ヒント が事実上の標準になり、ライブラリコードの大半に型が付くようになった
• match-case (3.10) — JavaScript の switch とは性格の異なるパターンマッチ
• 組み込みジェネリクス (3.9) — list[int], dict[str, int] をそのまま書ける
• Union の短縮記法 (3.10) — Optional[int] の代わりに int | None
• exception group (3.11) — except* で同時発生した例外を扱える
• free-threaded (3.13〜3.14, PEP 703/779) — GIL なしビルドが正式サポート段階に
• t-string (3.14, PEP 750) — f-string とは異なり、補間が遅延されるテンプレートリテラル
• lazy annotations (3.14, PEP 649/749) — アノテーションがデフォルトで遅延評価される

ツールチェーンも大きく入れ替わりました。pip の直接呼び出し、requirements.txt、virtualenv の手動アクティベーション といった昔の流れは、今ではほとんど使われません。代わりに、その役割をまとめて担うのが uv です。

旧コードを本書のスタイルに移す手順は付録A(旧Pythonコードを modern スタイルに移す)に別途まとめてあります。必要に応じて付録Aを参照してください。

uvとは何か #

uv は Astral (Ruff を作っているチーム) が開発している Rust 製のPythonパッケージ兼プロジェクトマネージャ です。ひとことで言えば次の通りです。

pip + pip-tools + pipx + poetry + pyenv + virtualenv を一つのバイナリにまとめた道具。

なぜこれが標準になりつつあるのか、短く比較すると次の通りです。

本書は uv を基本ツールとして使います。インタプリタ・仮想環境・依存関係・実行を、すべて uv ひとつで扱います。

インストール #

macOS / Linux:

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

Homebrew を使うなら:

brew install uv

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

WSL 環境で作業するなら、上の macOS/Linux 用コマンドをそのまま使えます。WSL 内のPythonとWindows側のPythonは別々に動作するので、どちらか一方を一貫して使うのが安全です。

インストール後、新しいターミナルを開いてバージョンを確認します。

uv --version
# uv 0.5.x  (またはそれ以降)

Python 3.14 のインストール #

uv は Python インタプリタ自体も直接インストールできます。pyenv を別で入れる必要はありません。

uv python install 3.14

インストール済みのインタプリタ一覧を見るには次の通りです。

uv python list --installed
# cpython-3.14.x-macos-aarch64-none ...

このインタプリタはシステムに恒久的にインストールされますが、PATH に直接露出するわけではありません。 uv がプロジェクトごとに自動で選んで使う仕組みです。システムの他のPythonと混ざらないので安全です。

最初のプロジェクト #

空のディレクトリを作って、uv init でプロジェクトを初期化します。

mkdir hello-py
cd hello-py
uv init --python 3.14

重要なのは --python 3.14 です。このプロジェクトは 3.14 に固定されます。別のプロジェクトが 3.12 を使っていても互いに干渉しません。コマンドを実行すると、次のファイルが生成されます。

hello-py/
├── .python-version    # 3.14
├── pyproject.toml     # プロジェクトメタデータ + 依存関係
├── README.md
└── main.py            # print("Hello from hello-py!")

pyproject.toml を開くと次のようになっています。

[project]
name = "hello-py"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = []

PEP 621 標準そのままの形式です。このファイルがプロジェクトの単一の定義 だと考えれば分かりやすいでしょう。依存関係、Pythonバージョン、ビルド情報、ツール設定(ruff/mypy など) がすべてここに集まります。requirements.txt、setup.py、setup.cfg を新しく作る場面はもうほとんどありません。

第5部のライブラリ公開(第32章) と型チェッカ設定(第30章) を扱うときも、結局は本章の pyproject.toml を拡張する形で進みます。

最初の実行 #

main.py をそのまま実行します。ただし python main.py ではなく、uv run main.py です。

uv run main.py
# Hello from hello-py!

uv run が行うことは次の通りです。

1. pyproject.toml の requires-python を満たすインタプリタを探す (なければ自動ダウンロード)
2. プロジェクトの仮想環境(.venv/) を自動で作り、uv.lock と同期する
3. その環境の中でコマンドを実行する

仮想環境を直接アクティベート(source .venv/bin/activate) する必要がなくなります。すべてのコマンドの前に uv run を付ける流れ に変わります。最初は慣れが必要ですが、慣れてしまえば「環境のアクティベートを忘れてシステムPythonにパッケージを入れてしまう」といった事故を減らせます。

依存関係の追加 #

パッケージを追加するときは uv add を使います。

uv add httpx

この一行で、次のことが同時に行われます。

• pyproject.toml の dependencies に httpx が追加される
• uv.lock に正確なバージョンとハッシュが記録される
• .venv/ にインストールされる

pyproject.toml をもう一度開くと次のようになります。

[project]
# ...
dependencies = [
    "httpx>=0.28.1",
]

開発時のみ必要なツール(テストランナー、リンター) は --dev グループに分けます。

uv add --dev pytest ruff

こうしておけば、配布時には除外され、開発時のみインストールされます。パッケージを外したいときは次の通りです。

uv remove httpx

もう一度 — 全体の流れ #

# 1. ツールのインストール (一度だけ)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. プロジェクトを作る
uv init my-app --python 3.14
cd my-app

# 3. 依存関係の追加
uv add httpx
uv add --dev pytest

# 4. 実行
uv run main.py
uv run pytest

旧来の流れと比べると、手順はここまで減ります。

# pyenv で Python をインストール
pyenv install 3.14.0
pyenv local 3.14.0

# venv を作る
python -m venv .venv
source .venv/bin/activate

# 依存関係インストール
pip install httpx
pip install pytest
pip freeze > requirements.txt

# 実行
python main.py

同じことをしますが、lock ファイルがないので再現性が低く、pip freeze は直接・間接の依存関係を区別できません。uv 側は最初から lock ベースなので、別のマシンでも正確に同じ環境が再現されます。

スクリプト単位で使う — もっと軽い場合 #

小さなスクリプトを 1 つだけ動かしたいとき、プロジェクトのセットアップすら重く感じるなら、スクリプト自体に依存関係を書く モードもあります。

# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx"]
# ///
import httpx

resp = httpx.get("https://httpbin.org/get")
print(resp.json())

実行するときは次の通りです。

uv run hello.py

uv は # /// の中に書かれた依存関係を認識し、一時的な環境を自動構成して実行します。使い捨てスクリプト、自動化、小さな道具を作るときに役立ちます。

第33章 CLI 道具作りでは、このスクリプト単位モードと正式なプロジェクトモードをどう使い分けるかを再び見ていきます。

練習問題 #

本章の環境が実際に整ったかを確認する短い実習です。

1. uv init で weather-py という名前の新しいプロジェクトを作り、httpx を依存関係として追加した後、main.py の中で https://httpbin.org/get を呼び出してレスポンスJSONを出力してください。実行は uv run main.py です。
2. 上のプロジェクトに --dev グループで pytest を追加し、uv run pytest --version が正常に動作するかを確認してください。pyproject.toml を開いて dependency-groups (もしくは [tool.uv.dev-dependencies]) セクションに pytest が入っていることを直接確認します。
3. スクリプト単位モードで # /// script ヘッダを持つ whoami.py を作成し (httpx 依存、https://httpbin.org/ip 呼び出し) 、別途プロジェクトディレクトリなしで uv run whoami.py 一行で実行できるかを確認してください。

一行まとめ: 本書は Python 3.14 と uv を標準として敷く。uv init ・ uv add ・ uv run の 3 コマンドが日常のすべてであり、すべてのプロジェクト設定は pyproject.toml 一枚に集まる。仮想環境の直接アクティベーションはもう行わない。

次の章 #

次の 第2章 変数、基本型と型ヒント では、本章で作った環境の上で最も基本となる — 型と型ヒント — を扱います。動的言語なのになぜ型を書くのか、int | None のようなモダンな記法、list[int] の組み込みジェネリクス、mypy / pyright まで整理します。