0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kilowatt

Windows向け uv環境構築 実践メモ: ライブラリ管理、Pythonの入れ方、pyproject.toml

0
Last updated at Posted at 2026-04-12

この記事では次の内容をまとめます。

  • ライブラリのインストール
  • Pythonはどのようにインストールされるのか
  • pyproject.toml とは何か
  • すでに pyproject.toml がある場合のインストール方法

できるだけ「なぜそうするのか」が分かるように書きます。

記事一覧: Windows向け uv環境構築 実践メモ: 記事一覧

先に結論

uv を使うと、Python開発でよく必要になる次の流れをかなり整理できます。

  1. Python本体を用意する
  2. プロジェクトを作る
  3. 必要なライブラリを追加する
  4. その内容を pyproject.toml で管理する

この流れが見えると、「今、自分は何をしているのか」が分かりやすくなります。

Pythonはどのようにインストールされるのか

uv は、すでにPCに入っているPythonを見つけて使うこともできます。
一方で、uv 自身がPythonを管理することもできます。

公式ドキュメントでは、uv が自前で管理するPythonを使えるようになっていて、必要なら自動ダウンロードもできます。

もう少しだけ正確に言うと、uv は uv 管理のPythonを入れるとき、Astral の python-build-standalone 系の配布物を利用します。
つまり、毎回 python.org から手でインストーラーを落としてくるのとは少し違います。

初心者向けには、まず次の理解で十分です。

  • PCにもともとあるPythonを使う場合がある
  • uv が管理するPythonを使う場合がある
  • 必要なら uv が自動で用意してくれる

たとえば明示的に入れるなら

uv python install 3.12

なぜ明示的に入れるのか

  • 使うPythonのバージョンを自分で決めやすい
  • プロジェクトごとの差を整理しやすい
  • 「どのPythonで動いているか」が分かりやすい

自動で入るケースもある

たとえば uv sync や uv run のようにPythonが必要なコマンドを実行したとき、必要なPythonがなければ uv が自動で取得することがあります。

これは初心者にとってかなり助かります。
最初に「Python本体をどこから入れるのか」で止まりにくいからです。

覚え方

  • すでにあるPythonを使うこともある
  • uv が管理するPythonを使うこともある
  • 足りなければ uv が入れてくれることがある

この理解で最初は十分です。

まずはプロジェクトを作る

uv では、プロジェクト管理の入り口として uv init が便利です。

プログラム開発したいフォルダでプロンプトを開き、以下を実行します。
以下の uv コマンドは、PowerShell とコマンドプロンプトのどちらでも同じです。

uv init
uv sync

すると、たとえば次のようなファイルやフォルダが作られます。

uv init が作るもの:

  • README.md
  • main.py
  • pyproject.toml
  • .python-version
  • .gitignore

uv sync が追加で作るもの:

  • .venv（仮想環境フォルダ）
  • uv.lock（インストール済みライブラリのバージョンを固定するファイル）

.venv の env は environment の略で、仮想環境の定番フォルダ名としてよく使われます。

なぜ uv init を使うのか

  • 最低限のひな形を自動で作ってくれる
  • 設定ファイルの置き場所が最初から整理される
  • 後で依存関係を管理しやすい

最初から手で全部作るより、初心者にはかなり楽です。

pyproject.toml とは何か

pyproject.toml は、Pythonプロジェクトの設定ファイルです。
「このプロジェクトの名前は何か」「どのPythonを対象にするか」「どんなライブラリを使うか」などをまとめて書く場所です。

かなりざっくり言うと、次のような役割があります。

  • プロジェクトの基本情報を持つ
  • 依存ライブラリを持つ
  • ツールの設定を書ける

たとえばこんなイメージ

[project]
name = "sample-app"
version = "0.1.0"
description = "uv sample project"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.32.0",
]

このファイルを使う理由

  • 必要なライブラリを文章ではなく設定として残せる
  • 他の人や未来の自分が見ても分かりやすい
  • 環境を再現しやすい

「このプロジェクトは何を前提に動くのか」を、口頭ではなくファイルに残すのが大事です。

PC交換や引き継ぎで強い理由

ここが、pyproject.toml を使う大きな価値です。

もし普段からPC全体にだけライブラリを入れていると、環境情報が頭の中にしか残らないことがあります。
すると、次のような場面で困ります。

  • 新しいPCに移したい
  • チームメンバーに渡したい
  • 数か月後に自分で触り直したい

一方で、pyproject.toml に依存関係が残っていれば、「このプロジェクトに何が必要か」がファイルとして見えます。
さらに uv では、uv.lock と uv sync を組み合わせることで、同じ環境をかなり再現しやすくなります。

uv.lock は、実際にインストールされたライブラリの正確なバージョンを記録するファイルです。
このファイルがあれば、uv sync を実行するだけで同じバージョンの環境を再現できます。

pyproject.toml の見方

  • name: プロジェクト名
  • version: バージョン
  • requires-python: 想定するPythonのバージョン
  • dependencies: 必要なライブラリ一覧

まずはこの4つが読めれば十分です。

すでに pyproject.toml がある場合のインストール方法

ここは、別のPCへ移したときや、他の人からプロジェクトを受け取ったときに大事です。

もし、すでにそのフォルダに pyproject.toml があるなら、uv init は基本的に不要です。
そのプロジェクトはもう初期化済みなので、必要なのは「環境をそろえること」です。

その場合は、プロジェクトのフォルダで次を実行します。

uv sync

なぜ uv init ではなく uv sync なのか

uv init は、新しいプロジェクトのひな形を作るコマンドです。
一方で、pyproject.toml がすでにあるなら、必要な情報はもう書かれています。

つまり、やりたいことは「作成」ではなく「再現」です。
そのため、uv sync を使って環境をそろえる方が自然です。

uv.lock がある場合

uv.lock も一緒にあるなら、uv sync でかなり同じ環境を再現しやすくなります。
公式ドキュメントでも、既存の uv.lock がある場合、uv sync はそのロック済みバージョンを優先すると説明されています。

これは、次のような場面で特に助かります。

  • PCを買い替えたとき
  • チームメンバーと環境をそろえたいとき
  • 昔のプロジェクトを動かし直したいとき

uv.lock がない場合

pyproject.toml はあるけれど uv.lock がない場合でも、uv sync は使えます。
この場合は、pyproject.toml の条件を見ながら依存関係を解決し、必要に応じて uv.lock を作ります。

ただし、この場合は「まったく同じバージョンの再現」ではなく、「条件に合う現在のバージョンで環境を作る」に近くなります。
再現性を重視するなら、uv.lock も一緒に管理した方が安心です。

ライブラリをインストールする

uv では、プロジェクトにライブラリを追加するときは uv add を使うのが分かりやすいです。

たとえば requests を追加するなら次です。

uv add requests

なぜ uv add を使うのか

uv add は単にライブラリを入れるだけではありません。

  • pyproject.toml を更新する
  • ロックファイルを更新する
  • 仮想環境にも反映する

つまり、「設定ファイル」と「実際の環境」をなるべくズレにくくしてくれます。

初心者のうちは、ここがかなり大切です。
手であちこち触るより、専用コマンドでそろえてもらう方がミスしにくいからです。

pip install ではだめなの？

だめではありません。
ただ、uv でプロジェクト管理をするなら、最初は uv add を使う方が分かりやすいです。

uv pip install は、どちらかというと既存の pip ワークフローに近い低レイヤーの操作です。
プロジェクト管理をしたいなら、まずは uv add を覚えるのがおすすめです。

実行例

uv add requests
uv run python -c "import requests; print(requests.__version__)"

uv run を使うと、プロジェクト用の環境を使ってコマンドを実行できます。

なぜ uv run を使うのか

  • どのPythonで実行するかを迷いにくい
  • プロジェクト用の仮想環境を使いやすい
  • 環境のズレを減らしやすい

.python-version は何のためにあるのか

uv init で作られることが多い .python-version は、「このプロジェクトではどのPython系統を使いたいか」を示すためのファイルです。

たとえば次のように固定できます。

uv python pin 3.12

すると、3.12 のような内容が .python-version に書かれます。

なぜ固定するのか

  • PCによって使うPythonが変わるのを防ぎやすい
  • チーム開発で揃えやすい
  • 数か月後の自分が見ても分かりやすい

どこまで覚えれば十分か

最初は次だけ覚えれば十分です。

  • uv init: プロジェクト作成
  • uv add パッケージ名: ライブラリ追加
  • uv run コマンド: 仮想環境を使って実行
  • uv python install 3.12: Python本体の用意
  • uv sync: 環境をそろえる

これらの uv コマンドは、PowerShell とコマンドプロンプトで同じ形で使えます。

このあたりが分かると、かなり実用レベルに入れます。

まとめ

今回のポイントは次のとおりです。

  • uv はPython本体も管理できる
  • pyproject.toml はプロジェクト設定の中心になるファイル
  • プロジェクトのライブラリ追加は uv add が分かりやすい
  • 環境情報をファイルに残しておくと、PC交換や引き継ぎで困りにくい

自分も最初は、Python本体、仮想環境、ライブラリ、設定ファイルの境目があいまいでした。
でも uv を使うと、その境目がかなり見えやすくなります。

初心者のうちは、まず「uv init して uv add して uv run する」と覚えるだけでも十分だと思います。

参考

補足

この記事は生成AIを活用して作成しました。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?