Pythonプロジェクトを作って動かす

uvを使って、Pythonのプロジェクトを作り、パッケージを入れ、プログラムとテストを動かすまでの流れを説明します。「環境構築」の「Pythonの環境をuvで作る」を終えていることが前提です。

全体の流れ

1. プロジェクトのフォルダを作って、uv init で初期化する
2. パッケージを追加する(uv add)
3. プログラムを書いて、実行する(uv run)
4. テストを書いて、実行する(uv run pytest)
5. Gitに記録する

手順1: プロジェクトを初期化する

WSL(Ubuntu)で、作業用のフォルダを作って、移動します。フォルダ名は、半角英数字がおすすめです。

mkdir -p ~/projects/py-sample
cd ~/projects/py-sample

uv init を実行します。

uv init

次のようなファイルが作られます。確認するには、ls -a を実行します。

.git/
.gitignore
.python-version
README.md
pyproject.toml
src/py_sample/__init__.py

ファイル	役割
pyproject.toml	プロジェクトの名前、使うPythonのバージョン、必要なパッケージを書く設定ファイル
.python-version	このプロジェクトで使うPythonのバージョン
src/py_sample/__init__.py	プログラムを書く場所。最初は「Hello」と表示する関数が入っています
README.md	プロジェクトの説明を書くファイル
.gitignore	Gitに記録しないファイルの一覧(.venv などが入っています)
.git/	Gitの記録の置き場所。uv init が、Gitの管理も始めてくれます

手順2: VS Codeで開く

code .

左下に「WSL: Ubuntu」と表示されることを確認します。

手順3: パッケージを追加する

プログラムで使うパッケージは、uv add で追加します。例として、Webにアクセスするための requests を追加します。

uv add requests

初回は、次のことが自動で行われます。

• 仮想環境 .venv が作られる
• requests と、必要なパッケージが入る
• pyproject.toml の dependencies に、requests が追記される
• 正確なバージョンを記録する uv.lock が作られる

手順4: プログラムを書いて、実行する

src/py_sample/__init__.py を、次のように書き換えます。

def add(a: int, b: int) -> int:
    return a + b


def main() -> None:
    print(f"1 + 2 = {add(1, 2)}")

実行します。uv init が作る pyproject.toml には、プロジェクト名のコマンドが登録されています。

uv run py-sample

1 + 2 = 3 と表示されれば成功です。

プロジェクトのフォルダに、自分で作ったPythonファイルを実行するときも、uv run を使います。

uv run python ファイル名.py

手順5: テストを書いて、実行する

テストには、定番の pytest を使います。

pytestを追加する

テストのための道具は、開発のときだけ必要です。--dev を付けて、開発用として追加します。

uv add --dev pytest

テストを書く

tests フォルダを作って、その中にテストのファイルを作ります。ファイル名は、test_ で始めます。

mkdir -p tests

tests/test_add.py を、次のように書きます。

from py_sample import add


def test_add():
    assert add(1, 2) == 3


def test_add_negative():
    assert add(-1, 1) == 0

テストを実行する

uv run pytest tests/ -v

-v を付けると、テストごとの結果が表示されます。次のように PASSED と表示されれば成功です。

tests/test_add.py::test_add PASSED                                       [ 50%]
tests/test_add.py::test_add_negative PASSED                              [100%]

============================== 2 passed in 0.01s ===============================

手順6: Gitに記録する

uv init で、Gitの管理はすでに始まっています。変更を記録します。

git add .
git commit -m "uvでプロジェクトを作成し、テストを追加"

.venv は、.gitignore に入っているため、記録されません。一方、uv.lock は 記録します。同じ環境を、あとから別の場所で再現できるようにするためです。

別のPCや、GitHubから取得したあと

プロジェクトを git clone で取得したら、次のコマンドで、同じ環境を作れます。

cd プロジェクトのフォルダ
uv sync

uv.lock に書かれたとおりに、仮想環境とパッケージが整います。

Claude Codeと使うとき

Claude Codeに頼むときは、確認の方法を一緒に伝える と、うまくいきます。

src/py_sample に、2つの数を掛ける関数 multiply を追加して。
tests/ にテストも書いて、uv run pytest tests/ -v が通るまで直して。

プロジェクトの CLAUDE.md に、使うコマンドを書いておくと、毎回伝えなくて済みます。

# コマンド
- テスト: `uv run pytest tests/ -v`
- パッケージの追加: `uv add パッケージ名`(開発用は `uv add --dev パッケージ名`)
- 実行: `uv run py-sample`

よく使うuvのコマンド

やりたいこと	コマンド
プロジェクトを初期化する	uv init
パッケージを追加する	uv add パッケージ名
開発用のパッケージを追加する	uv add --dev パッケージ名
パッケージを削除する	uv remove パッケージ名
環境を、uv.lock のとおりに整える	uv sync
プログラムを実行する	uv run コマンド
テストを実行する	uv run pytest tests/ -v

確認する

• uv init で、pyproject.toml などが作られた
• uv add requests で、.venv と uv.lock が作られた
• uv run py-sample で、プログラムが動いた
• uv run pytest tests/ -v で、テストが PASSED になった
• git commit で、変更を記録した

参考

• uvでプロジェクトを使う(公式)
• uvで依存関係を管理する(公式)