快速入门指南

July 19, 2026 · View on GitHub

1. 安装部署

X-AnyLabeling 提供了多种安装方法，您可以通过 pip 直接安装官方软件包获取最新的稳定版本，或通过克隆官方 GitHub 仓库进行源码安装，GUI 安装包也是一种便捷的选择。

Note

高级功能说明：以下高级功能仅适用于 Git 克隆方式，如需使用，请先参考对应的文档进行配置。

  1. 远程推理服务指南：基于 X-AnyLabeling-Server 的远程推理服务 - 安装指南
  2. 视频目标追踪：基于 Segment Anything 的视频目标追踪（SAM 2 | SAM 3）
  3. 目标候选框生成：基于 UPN 的目标候选框生成 - 安装指南
  4. 交互式检测分割：基于视觉和文本提示的交互式目标检测和分割 - 安装指南
  5. 智能检测分割：基于视觉提示、文本提示或免提示模式的目标检测与分割（YOLOE | SAM 3 | LocateAnything）
  6. 一键训练平台：基于 Ultralytics 框架的一键训练平台 - 安装指南
  7. 全模态视觉推理：基于 Rex-Omni 的目标检测、关键点检测（人、手、动物）、OCR、指向理解和视觉提示定位（安装指南）

1.1 前置条件

1.1.1 Miniconda

如果您已经在使用 Miniconda，可按以下步骤操作：

步骤 0. 从 官方网站 下载并安装 Miniconda。

步骤 1. 创建一个 Python 3.11 ~ 3.13 版本的 conda 环境（推荐 Python 3.12），并激活它。

Note

其他 Python 版本需要自行验证兼容性。

# CPU 环境 [Windows/Linux/macOS]
conda create --name x-anylabeling-cpu python=3.12 -y
conda activate x-anylabeling-cpu

# CUDA 11.x 环境 [Windows/Linux]
conda create --name x-anylabeling-cu11 python=3.12 -y
conda activate x-anylabeling-cu11

# CUDA 12.x 环境 [Windows/Linux]
conda create --name x-anylabeling-cu12 python=3.12 -y
conda activate x-anylabeling-cu12

# CUDA 13.x 环境 [Windows/Linux]
conda create --name x-anylabeling-cu13 python=3.12 -y
conda activate x-anylabeling-cu13

1.1.2 Venv

也可以使用 Python 内置的 venv 模块创建虚拟环境：

# CPU [Windows/Linux/macOS]
python3.12 -m venv venv-cpu
source venv-cpu/bin/activate  # Linux/macOS
# venv-cpu\Scripts\activate    # Windows

# CUDA 12.x [Windows/Linux]
python3.12 -m venv venv-cu12
source venv-cu12/bin/activate  # Linux
# venv-cu12\Scripts\activate    # Windows

# CUDA 11.x [Windows/Linux]
python3.12 -m venv venv-cu11
source venv-cu11/bin/activate  # Linux
# venv-cu11\Scripts\activate    # Windows

# CUDA 13.x [Windows/Linux]
python3.12 -m venv venv-cu13
source venv-cu13/bin/activate  # Linux
# venv-cu13\Scripts\activate    # Windows

1.1.3 uv

步骤 0. 安装 uv：

# Linux / macOS / WSL2
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

步骤 1. 创建虚拟环境（uv 会自动下载所需 Python 版本）并激活：

# CPU 环境 [Windows/Linux/macOS]
uv venv --python 3.12 .venv-cpu
source .venv-cpu/bin/activate      # Linux/macOS/WSL2
# .venv-cpu\Scripts\activate       # Windows

# CUDA 12.x 环境 [Windows/Linux]
uv venv --python 3.12 .venv-cu12
source .venv-cu12/bin/activate     # Linux
# .venv-cu12\Scripts\activate      # Windows

# CUDA 11.x 环境 [Windows/Linux]
uv venv --python 3.12 .venv-cu11
source .venv-cu11/bin/activate     # Linux
# .venv-cu11\Scripts\activate      # Windows

# CUDA 13.x 环境 [Windows/Linux]
uv venv --python 3.12 .venv-cu13
source .venv-cu13/bin/activate     # Linux
# .venv-cu13\Scripts\activate      # Windows

1.2 安装

1.2.1 Pip 安装（Beta 预发布版本）

您可以通过以下命令轻松安装 X-AnyLabeling 的最新 Beta 预发布版本（推荐使用 uv pip）：

pip install -U uv

# CPU [Windows/Linux/macOS]
uv pip install --pre "x-anylabeling-cvhub[cpu]"

# CUDA 12.x 是 GPU 版本的默认选项 [Windows/Linux]
uv pip install --pre "x-anylabeling-cvhub[gpu]"

# CUDA 11.x [Windows/Linux]
uv pip install --pre "x-anylabeling-cvhub[gpu-cu11]"

# CUDA 13.x [Windows/Linux]
uv pip install --pre "x-anylabeling-cvhub[gpu-cu13]"

1.2.2 Git 克隆（推荐）

步骤 a. 克隆代码仓库。

git clone https://github.com/CVHub520/X-AnyLabeling.git
cd X-AnyLabeling

步骤 b. 安装依赖。

pip install -U uv

# CPU [Windows/Linux/macOS]
uv pip install -e ".[cpu]"

# CUDA 12.x 是 GPU 版本的默认选项 [Windows/Linux]
uv pip install -e ".[gpu]"

# CUDA 11.x [Windows/Linux]
uv pip install -e ".[gpu-cu11]"

# CUDA 13.x [Windows/Linux]
uv pip install -e ".[gpu-cu13]"

如果您需要进行二次开发或打包编译，可同步安装 dev 依赖，例如：

uv pip install -e ".[cpu,dev]"

Note

如果切换到新的工程目录，请在该目录下重新执行一次上述安装命令，否则环境将引用旧目录中的源码。

安装完成后，可执行以下命令进行验证：

xanylabeling checks   # 显示系统及版本信息

您也可以运行以下命令获取其他信息：

xanylabeling help     # 显示帮助信息
xanylabeling version  # 显示版本号
xanylabeling config   # 显示配置文件路径

验证无误后，可直接运行应用程序：

xanylabeling

Tip

您可以通过 xanylabeling --help 查看所有可用的命令行选项。完整的参数说明请参考下方的命令行参数表格。

选项描述
filename指定图像或标签文件名。如果提供目录路径，则加载文件夹中的所有文件。
--help, -h显示帮助信息并退出。
--reset-config重置 Qt 配置，清除所有设置。
--logger-level设置日志记录级别：“debug”、“info”、“warning”、“fatal”、“error”。
--output, -O, -o指定输出文件或目录。以 .json 结尾的路径被视为文件。
--config指定配置文件或 YAML 格式的配置字符串。默认为用户特定路径。
--work-dir指定配置文件和数据文件的工作目录。默认为用户主目录。
--qt-image-allocation-limit以 MB 为单位覆盖 Qt 图像分配上限。Qt 默认值为 256 MB。设为 0 可完全禁用该限制。
--nodata防止在 JSON 文件中存储图像数据。
--autosave启用自动保存标注数据。
--nosortlabels禁用标签排序。
--flags逗号分隔的标志列表或包含标志的文件路径。
--labelflags用于标签特定标志的 YAML 格式字符串或包含 JSON 格式字符串的文件。
--labels逗号分隔的标签列表或包含标签的文件路径。
--validatelabel指定标签验证的类型。
--keep-prev保留上一帧的注释。
--no-auto-update-check禁用启动时的自动更新检查。

Note

依赖项列表以 pyproject.toml 为准。上述命令会安装所选运行环境所需的依赖。

此外，还支持多种标签格式之间的批量转换功能：

xanylabeling convert         # 列出所有支持的转换任务
xanylabeling convert <task>  # 查看特定转换任务的详细帮助和使用示例，例如：xlabel2yolo

Important

对于 GPU 加速，请按照以下说明，确保您本地的 CUDA 和 cuDNN 版本与 ONNX Runtime 版本兼容，并安装所需依赖库，以确保 GPU 加速推理正常运行：

CUDA 环境依赖选项ONNX Runtime GPUcuDNN
CUDA 11.xgpu-cu11>= 1.15.0, < 1.19.08.x
CUDA 12.xgpu>= 1.18.1, < 1.27.09.x
CUDA 13.xgpu-cu13>= 1.27.0, < 1.28.09.x

Warning

在同一个环境中只能安装 cpu、gpu-cu11、gpu 或 gpu-cu13 其中一个依赖选项。CUDA 11.x 还要求 onnx >= 1.15.0, < 1.16.1。

可选步骤：刷新翻译与资源文件

如果修改了界面文案或维护多语言文件，可使用以下命令刷新当前支持的界面语言（en_US、zh_CN、ja_JP、ko_KR）对应的翻译产物：

# 从源码字符串重新生成 .ts 目录
python scripts/generate_languages.py

# 编译 .qm 文件并重建 Qt 资源
python scripts/compile_languages.py

可选步骤：设置环境变量

# Linux 或 macOS
export PYTHONPATH=/path/to/X-AnyLabeling

# Windows
set PYTHONPATH=C:\path\to\X-AnyLabeling

Caution

避免依赖冲突：为避免与第三方包冲突，请先执行以下命令卸载旧版本：

pip uninstall anylabeling -y

Note

Fedora KDE 用户特别说明：如果遇到鼠标移动缓慢或响应延迟的问题，可以尝试使用 --qt-platform xcb 参数来提升性能：

xanylabeling --qt-platform xcb

1.2.3 GUI 安装包

下载链接: GitHub Releases

相比于从源代码运行，GUI 安装包提供了更便捷的使用体验，用户无需深入了解底层实现，只需解压即可直接使用。然而，GUI 安装包也存在一些局限性：

  • 故障排除困难：如果发生崩溃或错误，可能难以快速定位具体原因，从而增加了故障排除的难度。
  • 功能滞后：GUI 版本在功能上可能落后于源代码版本，可能会导致功能缺失和兼容性问题。
  • GPU 运行库要求：请根据 CUDA 11、12 或 13 选择对应安装包，并安装匹配的 CUDA 和 cuDNN 运行库。无法加载所需 GPU 库时，应用会回退到 CPU。

因此，建议根据具体需求和使用场景，在从源代码运行和使用 GUI 安装包之间做出选择，以优化使用体验。

2. 使用方法

有关如何使用 X-AnyLabeling 的详细说明，请参考相应的用户手册。

3. 打包编译

Note

请注意，以下步骤是可选的。此部分针对可能需要定制和编译软件以适应特定部署场景的用户。如果您使用软件时没有此类需求，可以跳过此部分。

展开/收起

为了方便用户在不同平台上运行 X-AnyLabeling，该工具提供了打包和编译的说明以及相关注意事项。执行对应打包命令前，请先安装目标运行环境的依赖选项。

3.1 注意事项

  • 验证 GPU 环境：如果编译 GPU 版本，请先激活相应的 GPU 运行环境，并执行 pip list | grep onnxruntime-gpu 以确保其正确安装。

  • GPU 编译：GPU 规格文件会自动收集 ONNX Runtime Provider 库。构建前安装 gpu-cu11、gpu 或 gpu-cu13，即可分别选择 CUDA 11、12 或 13。详细兼容性信息请参考官方文档。

3.2 编译命令

# Windows-CPU
bash scripts/build_executable.sh win-cpu

# Windows-GPU
bash scripts/build_executable.sh win-gpu

# Linux-CPU
bash scripts/build_executable.sh linux-cpu

# Linux-GPU
bash scripts/build_executable.sh linux-gpu

# macOS
bash scripts/build_executable.sh macos

Tip

如果在 Windows 上执行上述命令时遇到权限问题，在确保完成上述准备步骤后，可以直接执行以下命令：

pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-cpu.spec
pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec