DORA中文社区
  • 简体中文

      • 2.2 Python 与 uv

      DORA 的 Python 节点需要一个 Python 运行时和一个包管理器来安装依赖。本课程推荐使用 uv——一个用 Rust 编写的极速 Python 包管理器（比 pip 快 10-100 倍），它同时内置 Python 版本管理功能。

      安装 uv

      macOS / Linux
      Windows
      curl -LsSf https://astral.sh/uv/install.sh | sh
      重要！装完了，但还没生效

      uv 已经装到电脑上了，但你当前的终端窗口还不知道——它还在用安装前的环境，不知道 PATH 里多了 uv。

      选下面任一种让 uv 生效：

      • 方式一（推荐）： 关掉当前终端，重新打开一个新终端。

      • 方式二（立即生效）： 在当前终端执行：

        source ~/.cargo/env

        为什么是 cargo 的路径？因为 uv 也是 Rust 生态的一部分，它把自己装在 ~/.cargo/bin/ 下，和 Rust 工具链共用同一个目录。

      确认一切就绪：

      uv --version
# 应输出版本号，如 uv 0.5.x
      uv 的功能

      uv 同时扮演了 pip（包安装）和 pyenv（Python 版本管理）的角色。安装后可直接用 uv python install 安装指定版本 Python，用 uv pip install 装包。

      安装 Python

      uv 安装完成后，用它安装本课程使用的 Python 版本：

      uv python install 3.12

      安装完成后，可用以下命令验证：

      uv run python --version
# 应输出 Python 3.12.x
      关于系统 Python

      macOS 和 Linux 通常自带 Python，但不建议直接使用系统 Python（版本可能过旧，且安装包可能污染系统环境）。使用 uv 管理的 Python 是隔离的，不会影响系统自带的版本。

      创建虚拟环境

      后续所有 Python 节点都在 uv 虚拟环境中运行，保证依赖隔离、版本一致。在课程工作目录下创建虚拟环境：

      # 在课程工作目录下执行
uv venv

      此命令会创建 .venv/ 目录，包含一个独立的 Python 环境。

      Tip

      .venv 是隐藏目录 在 macOS/Linux 中，以 . 开头的文件或目录默认为隐藏文件，ls 命令不会显示。如需查看，请使用：

      ls -a        # 列出所有文件（含隐藏文件）
ls -la       # 详细格式列出所有文件

      文件管理器中也可显示隐藏文件：

      • Linux（Nautilus 等）：按 Ctrl + H
      • macOS Finder：按 Cmd + Shift + .

      Windows 系统没有此隐藏约定，.venv 目录默认可见。

      每次开始课程操作前，需要激活虚拟环境：

      macOS / Linux
      Windows
      source .venv/bin/activate

      激活后终端提示符前会显示 (.venv)，表示当前在虚拟环境中：

      (.venv) $ python --version
Python 3.12.x
      后续操作默认在虚拟环境中

      从本章之后的课程中，python xxx.py、pip install xxx 等命令都默认在虚拟环境中执行。每次新开终端都要先执行 source .venv/bin/activate（Windows 为 .venv\Scripts\activate）。

      安装依赖

      虚拟环境激活后，安装课程所需的 Python 包：

      # 安装 pyarrow（DORA Python 节点必需）
uv pip install pyarrow

# 后续各章用到的包，如 opencv-python、ultralytics、sherpa-onnx 等，
# 在对应章节会单独说明，使用时按需安装即可。

      小结

      • 使用 uv 安装和管理 Python 环境。
      • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
      • Windows: PowerShell 运行安装脚本。
      • uv python install 3.12 安装课程使用的 Python 版本。
      • uv venv 创建虚拟环境，每次新开终端先激活（source .venv/bin/activate 或 Windows 的 .venv\Scripts\activate）。
      • uv 隔离管理 Python，不冲突系统自带版本。