X-AnyLabeling 提供了多种安装方法，您可以通过 pip 直接安装官方软件包获取最新的稳定版本，或通过克隆官方 GitHub 仓库进行源码安装，GUI 安装包也是一种便捷的选择。
Note
高级功能说明：以下高级功能仅适用于 Git 克隆方式，如需使用，请先参考对应的文档进行配置。
如果您已经在使用 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也可以使用 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步骤 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您可以通过以下命令轻松安装 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]"步骤 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]"如果您需要进行二次开发或打包编译，可同步安装 dev 依赖，例如：
uv pip install -e ".[cpu,dev]"Note
如果切换到新的工程目录，请在该目录下重新执行一次上述安装命令，否则环境将引用旧目录中的源码。
安装完成后，可执行以下命令进行验证：
xanylabeling checks # 显示系统及版本信息您也可以运行以下命令获取其他信息：
xanylabeling help # 显示帮助信息
xanylabeling version # 显示版本号
xanylabeling config # 显示配置文件路径验证无误后，可直接运行应用程序：
xanylabelingTip
您可以通过 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
请参阅 X-AnyLabeling pyproject.toml 文件以获取依赖项列表。请注意，以上所有示例都安装了所有必需的依赖项。
此外，还支持多种标签格式之间的批量转换功能：
xanylabeling convert # 列出所有支持的转换任务
xanylabeling convert <task> # 查看特定转换任务的详细帮助和使用示例，例如：xlabel2yoloImportant
对于 GPU 加速，请按照以下说明，确保您本地的 CUDA 和 cuDNN 版本与 ONNX Runtime 版本兼容，并安装所需依赖库，以确保 GPU 加速推理正常运行：
Warning
对于 CUDA 11.x 环境，请务必确保版本满足以下要求：
onnx >= 1.15.0, < 1.16.1onnxruntime-gpu >= 1.15.0, < 1.19.0
可选步骤：刷新翻译与资源文件
如果修改了界面文案或维护多语言文件，可使用以下命令刷新当前支持的界面语言（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-AnyLabelingCaution
避免依赖冲突：为避免与第三方包冲突，请先执行以下命令卸载旧版本：
pip uninstall anylabeling -yNote
Fedora KDE 用户特别说明：如果遇到鼠标移动缓慢或响应延迟的问题，可以尝试使用 --qt-platform xcb 参数来提升性能：
xanylabeling--qt-platform xcb下载链接: GitHub Releases
相比于从源代码运行，GUI 安装包提供了更便捷的使用体验，用户无需深入了解底层实现，只需解压即可直接使用。然而，GUI 安装包也存在一些局限性：
- 故障排除困难：如果发生崩溃或错误，可能难以快速定位具体原因，从而增加了故障排除的难度。
- 功能滞后：GUI 版本在功能上可能落后于源代码版本，可能会导致功能缺失和兼容性问题。
- GPU 加速限制：鉴于硬件和操作系统环境的多样性，当前的 GPU 推理加速服务需要用户根据需要从源代码编译。
因此，建议根据具体需求和使用场景，在从源代码运行和使用 GUI 安装包之间做出选择，以优化使用体验。
有关如何使用 X-AnyLabeling 的详细说明，请参考相应的用户手册。
Note
请注意，以下步骤是可选的。此部分针对可能需要定制和编译软件以适应特定部署场景的用户。如果您使用软件时没有此类需求，可以跳过此部分。
展开/收起
为了方便用户在不同平台上运行 X-AnyLabeling，该工具提供了打包和编译的说明以及相关注意事项。在执行以下打包命令之前，请根据您的环境和要求修改 app_info.py 文件中的 __preferred_device__ 参数，以选择适当的 GPU 或 CPU 版本进行构建。
-
修改设备配置：在编译之前，请确保
anylabeling/app_info.py文件中的__preferred_device__参数已根据所需的 GPU/CPU 版本进行修改。 -
验证 GPU 环境：如果编译 GPU 版本，请先激活相应的 GPU 运行环境，并执行
pip list | grep onnxruntime-gpu以确保其正确安装。 -
Windows-GPU 编译：手动修改
packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec文件中的datas列表参数，以将本地onnxruntime-gpu动态库的相关*.dll文件添加到列表中。 -
Linux-GPU 编译：手动修改
packaging/pyinstaller/specs/x-anylabeling-linux-gpu.spec文件中的datas列表参数，以将本地onnxruntime-gpu动态库的相关*.so文件添加到列表中。此外，请确保根据您的 CUDA 版本下载匹配的onnxruntime-gpu包。有关详细的兼容性信息，请参阅官方文档。
# 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