文章目录一、uv 是什么为什么需要 uv二、安装 uvmacOS / LinuxWindows验证安装三、核心命令速查表四、实战从零开始管理项目场景 1创建全新项目场景 2接管现有项目如 MiroFish场景 3指定 Python 版本场景 4运行 Python 脚本五、uv 与传统工具对比对比 pip对比 Poetry六、高级技巧1. 查看依赖树2. 检查依赖冲突3. 更新依赖4. 导出 requirements.txt5. 从 requirements.txt 迁移七、MiroFish 项目中的 uv 实践八、常见问题Q1: uv 创建的虚拟环境在哪里Q2: 如何删除虚拟环境重新创建Q3: uv 和 pip 能混用吗Q4: 如何指定国内镜像源九、总结一、uv 是什么uv是由 Astral 团队开发的 Python 包管理工具用 Rust 编写目标是替代pip、poetry、conda等传统工具。它的核心特点是极速——比 pip 快 10-100 倍。为什么需要 uv想象 Python 包管理是一条物流系统传统工具问题uv 的解决方案pip venv串行下载、无全局缓存并行下载 全局缓存poetry解析依赖慢、lock 文件复杂Rust 实现、毫秒级解析conda环境臃肿、启动慢轻量级虚拟环境二、安装 uvmacOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|shWindowspowershell-ExecutionPolicy ByPass-cirm https://astral.sh/uv/install.ps1 | iex验证安装uv--version# 输出: uv 0.9.26 (或更高版本)三、核心命令速查表┌─────────────────┬─────────────────────────────────────┐ │ 命令 │ 作用 │ ├─────────────────┼─────────────────────────────────────┤ │ uv venv │ 创建虚拟环境 │ │ uv sync │ 同步依赖根据 pyproject.toml │ │ uv add │ 添加依赖包 │ │ uv remove │ 移除依赖包 │ │ uv run │ 在虚拟环境中运行命令 │ │ uv pip install │ 兼容 pip 的安装方式 │ │ uv lock │ 生成/更新 uv.lock 文件 │ └─────────────────┴─────────────────────────────────────┘四、实战从零开始管理项目场景 1创建全新项目# 1. 创建项目目录mkdirmyprojectcdmyproject# 2. 初始化 Python 项目生成 pyproject.tomluv init--python3.11# 3. 添加依赖uvaddflask requests# 4. 添加开发依赖仅开发时使用uvadd--devpytest black# 5. 查看生成的 pyproject.tomlcatpyproject.toml生成的pyproject.toml示例[project] name myproject version 0.1.0 description Add your description here requires-python 3.11 dependencies [ flask3.0.0, requests2.31.0, ] [project.optional-dependencies] dev [ pytest8.0.0, black24.0.0, ]场景 2接管现有项目如 MiroFish# 进入已有 pyproject.toml 的项目cd/Users/lianggao/MyWorkSpace/001-360/personal/MiroFish-main/backend# 一键同步所有依赖uvsync# 这会# - 创建 .venv/ 虚拟环境# - 安装 pyproject.toml 中所有依赖# - 生成 uv.lock 锁定文件场景 3指定 Python 版本# 方式 1命令行指定uvsync--python3.11uvsync--python/usr/local/bin/python3.11# 方式 2环境变量UV_PYTHON3.11uvsync# 方式 3项目固定版本推荐echo3.11.python-version场景 4运行 Python 脚本# 无需手动激活虚拟环境uv run python app.py# 运行模块uv run python-mpytest# 运行命令行工具uv run flask--appapp run五、uv 与传统工具对比对比 pip操作pip 方式uv 方式创建环境python -m venv .venvuv venv安装依赖pip install -r requirements.txtuv sync或uv pip install运行脚本source .venv/bin/activate python app.pyuv run python app.py速度慢串行快并行 缓存对比 Poetry特性Poetryuv依赖解析较慢毫秒级lock 文件poetry.lockuv.lock虚拟环境自动管理自动管理构建后端内置支持 hatchling 等六、高级技巧1. 查看依赖树uv pip tree2. 检查依赖冲突uv pip check3. 更新依赖# 更新所有依赖到最新版本uvsync--upgrade# 更新单个包uvaddflask--upgrade4. 导出 requirements.txtuv pip freezerequirements.txt5. 从 requirements.txt 迁移# 一次性安装 requirements.txt 中的所有包uv pipinstall-rrequirements.txt# 然后转换为 pyproject.toml 管理推荐uvadd$(catrequirements.txt|grep-v^#)七、MiroFish 项目中的 uv 实践在 MiroFish 项目中uv 的配置如下package.jsonsetup:backend:cd backend uv sync,backend:cd backend uv run python run.pybackend/pyproject.tomlrequires-python 3.11 dependencies [ flask3.0.0, openai1.0.0, zep-cloud3.13.0, camel-oasis0.2.5, # ... 其他依赖 ]日常开发流程# 1. 安装后端依赖npmrun setup:backend# 2. 启动后端服务使用 uv runnpmrun backend# 或同时启动前后端npmrun dev八、常见问题Q1: uv 创建的虚拟环境在哪里在项目的.venv/目录下与 poetry 类似。Q2: 如何删除虚拟环境重新创建rm-rf.venv uvsyncQ3: uv 和 pip 能混用吗不建议。uv 使用自己的元数据格式混用可能导致状态不一致。Q4: 如何指定国内镜像源# 设置环境变量exportUV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple# 或在 pyproject.toml 中配置[[tool.uv.index]]urlhttps://pypi.tuna.tsinghua.edu.cn/simpledefaulttrue九、总结uv 是 Python 包管理的新一代标准它的核心价值在于极速Rust 实现并行下载全局缓存简单一条命令完成环境创建 依赖安装兼容支持 pyproject.toml 标准易于迁移统一替代 pip venv poetry 的组合对于 MiroFish 这样的全栈项目uv 让 Python 后端的依赖管理变得和前端 npm 一样简单高效。
/YOLO渣土车检测)
