标签 linux 下的文章

uv 的管理逻辑非常简单：以项目为单位，自动处理从 Python 版本到依赖包的一切。你不用再手动操心创建和激活环境的事，uv 会帮你把一切都整理得井井有条。

🚀 5分钟核心配置：从安装到运行

这是配置并运行一个 uv 管理项目的标准流程：

  1. 安装 uv：在终端中运行对应系统的命令。

    • macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
    • Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. 初始化新项目：在项目文件夹内，用 uv init 一键生成基础配置文件。

    uv init my-project
cd my-project

    这条命令会自动创建 pyproject.toml 文件，它声明了项目的所有依赖和元数据，是项目配置的核心。

  3. 添加依赖并自动创建环境：使用 uv add 添加依赖，如果虚拟环境不存在，uv 会自动创建。依赖会记录在 pyproject.toml 文件中。

    uv add requests
    • uv 会在当前目录下创建一个名为 .venv 的虚拟环境，用于隔离项目依赖。
    • 如果系统缺少所需的 Python 版本，uv 会自动下载并安装。

  4. 自动运行脚本：使用 uv run，无需手动激活虚拟环境。

    uv run python main.py

    它会自动找到项目里的 .venv 环境，并在其中运行你的代码，极大简化了开发流程。

完成以上步骤，你就成功运行了一个由 uv 全程管理的 Python 项目。整个过程无需手动安装 Python、创建或激活虚拟环境，uv 会自动完成。

🛠️ 常用场景进阶配置

如果你有更具体的需求，可以参考下面这些进阶用法。

🐍 精细管理 Python 版本

或许你不想用 uv 自动下载的版本，而是想精确控制项目的 Python 版本。

  • 安装并指定 Python 版本：显式安装你需要的 Python 版本。

    uv python install 3.11
# 创建项目时，使用 --python 参数直接指定
uv init --python 3.11 my-project
cd my-project
# 或者为现有项目固定 Python 版本
uv python pin 3.11

    固定版本后，uv 会记录在 pyproject.toml 中，团队成员后续同步时会同此配置。

  • 强制使用系统 Python：

    uv venv --python 3.12 --no-managed-python

    这会强制 uv 使用系统安装的 Python 3.12 版本来创建虚拟环境。

☁️ 配置国内镜像源加速

为提升依赖安装速度，可配置国内镜像源（如清华源）。

  • Windows: $env:UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
  • macOS/Linux: export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

🗂️ 使用 pyproject.toml 进行高级配置

uv 的配置信息除了环境变量，主要集中在项目下的 pyproject.toml 文件中。该文件是 Python 项目的现代配置标准，uv 的各项参数都可以在这里以 [tool.uv] 的形式设置。

配置文件同时支持用户级 ~/.config/uv/uv.toml 和项目级 pyproject.toml。

💡 与常用 IDE 的集成

🧩 PyCharm (2024.3.2+)

  • 在创建新项目时，直接在“环境类型 (Environment type)”中选择 uv，PyCharm 会自动检测 uv 并配置好一切。
  • 如果 PyCharm 没有自动检测到 uv，你可以在“添加本地解释器 (Add Local Interpreter)”中选择 uv 环境，然后手动指定 uv 可执行文件的路径。

📝 VS Code

  1. 用 uv 创建并进入虚拟环境后，执行 uv run python -m pip install ipykernel 来安装内核。
  2. 在VS Code中按 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux)，选择 Python: Select Interpreter。
  3. 在弹出的列表中，uv 创建的 .venv 环境会自动被列出，选择它即可。

⚙️ 常用 uv 命令速查

  • uv init: 在当前目录初始化一个新项目，生成 pyproject.toml。
  • uv add <package>: 添加项目依赖并更新锁定文件。
  • uv remove <package>: 移除项目依赖。
  • uv sync: 同步项目的环境与 pyproject.toml 和 uv.lock 文件。
  • uv run <script>: 在项目的虚拟环境中自动运行命令。
  • uv python install <version>: 安装指定的 Python 版本。
  • uv python list: 列出所有可用的 Python 版本。
  • uv tool install <tool>: 安装并管理全局的命令行工具。

💎 总结

uv 的核心思想是“项目即环境”，将配置、依赖和运行完全自动化，免去了手动创建、激活、切换等繁琐步骤。它是一个集 Python 版本管理、虚拟环境管理、依赖管理于一体的现代化高效工具。