notes/resource/python/python.md

一、项目初始化

场景	命令	说明
创建新项目	uv init my-project	生成项目目录、pyproject.toml、.python-version
在已有目录初始化	uv init	当前目录下初始化，不新建子目录
指定 Python 版本创建	uv init --python 3.12 my-project	锁定 Python 版本
创建库项目（不是应用）	uv init --lib	生成适合打包发布的结构

二、虚拟环境

场景	命令	说明
创建虚拟环境	uv venv	自动创建 .venv
创建时指定 Python	uv venv --python 3.12	用特定版本
创建时带 pip	uv venv --seed	装上 pip 和 setuptools
激活环境	.venv\Scripts\activate（Windows）	跟标准 venv 一样
删除环境	Remove-Item -Recurse -Force .venv	删掉即可，之后能重新创建

三、依赖管理（核心流程）

添加依赖

命令	说明
uv add numpy	安装并写入 pyproject.toml
uv add pandas --dev	安装为开发依赖
uv add "numpy>=2.0,<3.0"	带版本约束
uv add git+https://github.com/user/repo.git	从 Git 安装
uv add ./local-package	从本地路径安装

移除依赖

命令	说明
uv remove numpy	卸载并从 pyproject.toml 移除

同步/安装

命令	说明
uv sync	根据锁文件安装所有依赖（有锁文件时）
uv sync --no-dev	只安装正式依赖，跳过开发依赖
uv lock	生成/更新 uv.lock 锁文件
uv lock --upgrade-package numpy	只升级指定包的锁版本
uv tree	查看依赖树

四、用 uv 运行/执行

命令	说明
uv run python main.py	在项目环境中运行脚本
uv run python	进入项目环境的 Python 交互模式
uv run pytest	运行项目中的测试
uv run ipython	运行任意命令，自动使用当前环境
uv run --with requests python	临时加一个包再运行（不写入依赖）
uvx ruff check .	运行一次性工具（等同于 uv tool run）

五、Python 版本管理

命令	说明
uv python list	查看已安装的 Python 版本
uv python install 3.12	安装指定版本
uv python pin 3.12	为当前项目锁定 Python 版本

六、典型工作流

从头开始一个项目

# 1. 创建项目
uv init myproject
cd myproject

# 2. 添加依赖（自动创建 .venv 并安装）
uv add numpy pandas

# 3. 写代码...

# 4. 运行
uv run python main.py

克隆已有项目

# 1. 克隆
git clone <url>
cd project

# 2. 一键装上所有依赖
uv sync

# 3. 运行
uv run python main.py

用 pip 风格的即时安装（不写 pyproject.toml）

# 只是装个包试试，不想污染项目定义
uv pip install requests
uv pip list
uv pip uninstall requests