基礎編では、新しいプロジェクトの開始から依存関係の更新まで、1ステップずつ説明します。
前提
- Apple Silicon Macを使用
- Homebrewによるパッケージ管理
環境構築 Step-by-step
ホームディレクトリ（/Users/xxxxx）から開始するものとする。
プロジェクトの作成
uv initで新しいプロジェクトnew-projectを作成する。
$ uv init new-project
uv init new-project
Initialized project `new-project` at `/Users/xxxxx/new-project`
new-projectディレクトリに移動する。
$ cd /Users/xxxxx/new-project
この時点で、new-projectディレクトリには、以下の6つのファイルが作成されている。
.git
.gitignore
.python-version
README.md
main.py
pyproject.toml
.git .gitignoreは、Git関連ファイル（Git編・GitHub連携編）。
.python-versionの内容。
3.13
README.mdは空。
main.pyの内容は必要最低限のテンプレート。
def main():
print("Hello from new-project!")
if __name__ == "__main__":
main()
とりあえず、uv runで実行してみる。
$ uv run main.py
uv run main.py
Hello from new-project!
pyproject.tomlの内容。依存関係dependenciesは、まだ記述なし。
[project]
name = "new-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []
Pythonのバージョンを指定して仮想環境を作る。システムデフォルトのバージョンのままならば、uv envだけでよい。
$ uv venv --python 3.13.5
uv venv --python 3.13.5
Using CPython 3.13.5
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
仮想環境関係ファイルを保管する.venvディレクトリが作成される。
仮想環境を有効にする。
$ source .venv/bin/activate
uv pip installで必要なパッケージをインストールする。
$ uv pip install requests
uv pip install requests
Resolved 5 packages in 51ms
Installed 5 packages in 7ms
+ certifi==2025.7.14
+ charset-normalizer==3.4.2
+ idna==3.10
+ requests==2.32.4
+ urllib3==2.5.0
依存関係の管理
必要に応じて、依存関係をプロジェクトファイルに追加する。
$ uv add requests
uv add requests
Resolved 6 packages in 4ms
Audited 5 packages in 0.04ms
依存関係の詳細を記録したuv.lockファイルが作成される。
追加後のpyproject.tomlの内容。dependenciesに依存情報"requests>=2.32.4",が追記されている。
[project]
name = "new-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
"requests>=2.32.4",
]
uv removeでpyproject.toml内の依存情報を削除できる。
uv addで、依存関係も含めてpandasをインストールしてみる。
$ uv add pandas
uv add pandas
Resolved 12 packages in 60ms
Installed 6 packages in 40ms
+ numpy==2.3.2
+ pandas==2.3.1
+ python-dateutil==2.9.0.post0
+ pytz==2025.2
+ six==1.17.0
+ tzdata==2025.2
追加後のpyproject.tomlの内容。依存情報"pandas>=2.3.1",が追記されている。
[project]
name = "new-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
"pandas>=2.3.1",
"requests>=2.32.4",
]
uv treeで確認した依存関係の構造はこんな感じ。
uv tree
Resolved 12 packages in 0.75ms
new-project v0.1.0
├── pandas v2.3.1
│ ├── numpy v2.3.2
│ ├── python-dateutil v2.9.0.post0
│ │ └── six v1.17.0
│ ├── pytz v2025.2
│ └── tzdata v2025.2
└── requests v2.32.4
├── certifi v2025.7.14
├── charset-normalizer v3.4.2
├── idna v3.10
└── urllib3 v2.5.0
手動でpyproject.tomlから"pandas>=2.3.1",行を削除した後、環境をuv syncで同期してみる。
$ uv sync
pandasとその依存パッケージがアンインストールされる。
uv sync
Resolved 6 packages in 2ms
Uninstalled 6 packages in 160ms
- numpy==2.3.2
- pandas==2.3.1
- python-dateutil==2.9.0.post0
- pytz==2025.2
- six==1.17.0
- tzdata==2025.2
Pythonのインタプリタで確認。
Python 3.13.5 (main, Jul 23 2025, 00:18:28) [Clang 20.1.4 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import requests
>>> import pandas
Traceback (most recent call last):
File "<python-input-1>", line 1, in <module>
import pandas
ModuleNotFoundError: No module named 'pandas'
>>>
パッケージ内の依存関係も、uvが自動管理してくれるので便利。
まとめ
一連の流れをまとめます。
uv init [project]-
[project]ディレクトリに移動 uv venv --python [version]-
uv pip install [packages]またはuv add [packages] - 必要に応じて、
uv remove [packages]またはマニュアルでpyproject.tomlを編集、uv syncで環境を同期。
Tips
入力ウインドウが、trminalモード>_なのか、AgentモードAなのか気をつける（ウインドウ左下にアイコンが表示されている）。Agentモードのときにコマンドを入力すると、AIがいったん考えた後に同じコマンドを入力するので、二度手間で時間もかかりイラつくので注意。
⌘+Iで、terminalとAgentモードを切り替えられる。