Skip to content

快速开始

安装Ultralytics

Ultralytics提供了多种安装方法，包括pip、conda和Docker。通过ultralytics pip包安装YOLO以获取最新的稳定版本，或通过克隆Ultralytics GitHub仓库获取最新版本。Docker可用于在隔离容器中执行包，避免本地安装。



观看: Ultralytics YOLO快速入门指南

安装

PyPI - Python版本

使用pip安装ultralytics包，或通过运行pip install -U ultralytics更新现有安装。访问Python包索引（PyPI）以获取更多关于ultralytics包的详细信息：https://pypi.org/project/ultralytics/。

PyPI - 版本 下载量

# 从PyPI安装ultralytics包
pip install ultralytics

您也可以直接从GitHub仓库安装ultralytics包。如果您想要最新的开发版本，这可能很有用。确保您的系统上安装了Git命令行工具。@main命令安装main分支，可以修改为另一个分支，即@my-branch，或完全删除以默认使用main分支。

# 从GitHub安装ultralytics包
pip install git+https://github.com/ultralytics/ultralytics.git@main

Conda是pip的替代包管理器，也可用于安装。访问Anaconda以获取更多详细信息：https://anaconda.org/conda-forge/ultralytics。Ultralytics的conda包更新仓库位于https://github.com/conda-forge/ultralytics-feedstock/。

Conda版本 Conda下载量 Conda配方 Conda平台

# 使用conda安装ultralytics包
conda install -c conda-forge ultralytics

Note

如果您在CUDA环境中安装，最佳实践是在同一命令中安装ultralytics、pytorch和pytorch-cuda，以允许conda包管理器解决任何冲突，或者在最后安装pytorch-cuda，以允许其在必要时覆盖CPU特定的pytorch包。 

# 使用conda一起安装所有包
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics

Conda Docker镜像

Ultralytics Conda Docker镜像也可从DockerHub获取。这些镜像基于Miniconda3，是开始在Conda环境中使用ultralytics的简单方式。

# 将镜像名称设置为变量
t=ultralytics/ultralytics:latest-conda

# 从Docker Hub拉取最新的ultralytics镜像
sudo docker pull $t

# 在支持GPU的容器中运行ultralytics镜像
sudo docker run -it --ipc=host --gpus all $t  # 所有GPU
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t  # 指定GPU

克隆 ultralytics 仓库，如果你有兴趣为开发做出贡献或希望尝试最新的源代码。克隆后，导航到目录并使用 pip 以可编辑模式 -e 安装包。

GitHub 最新提交 GitHub 提交活动

# 克隆 ultralytics 仓库
git clone https://github.com/ultralytics/ultralytics

# 导航到克隆的目录
cd ultralytics

# 以可编辑模式安装包以进行开发
pip install -e .

使用 Docker 轻松在隔离容器中执行 ultralytics 包，确保在各种环境中一致且顺畅的性能。通过从 Docker Hub 选择一个官方的 ultralytics 镜像，你不仅避免了本地安装的复杂性，还能访问一个经过验证的工作环境。Ultralytics 提供 5 个主要的受支持 Docker 镜像，每个镜像都设计为在不同平台和用例中提供高兼容性和效率：

Docker 镜像版本 Docker 拉取次数

  • Dockerfile: 推荐用于训练的 GPU 镜像。
  • Dockerfile-arm64: 针对 ARM64 架构优化，允许在 Raspberry Pi 和其他基于 ARM64 的平台上部署。
  • Dockerfile-cpu: 基于 Ubuntu 的仅 CPU 版本，适用于推理和没有 GPU 的环境。
  • Dockerfile-jetson: 专为 NVIDIA Jetson 设备定制，集成了针对这些平台的 GPU 支持优化。
  • Dockerfile-python: 仅包含 Python 和必要依赖项的最小镜像，适用于轻量级应用和开发。
  • Dockerfile-conda: 基于 Miniconda3，包含 conda 安装的 ultralytics 包。

以下是获取最新镜像并执行的命令：

# 将镜像名称设置为变量
t=ultralytics/ultralytics:latest

# 从 Docker Hub 拉取最新的 ultralytics 镜像
sudo docker pull $t

# 在支持 GPU 的容器中运行 ultralytics 镜像
sudo docker run -it --ipc=host --gpus all $t  # 所有 GPU
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t  # 指定 GPU

上述命令使用最新的 ultralytics 镜像初始化一个 Docker 容器。-it 标志分配一个伪 TTY 并保持 stdin 打开，使你能够与容器交互。--ipc=host 标志将 IPC（进程间通信）命名空间设置为主机，这对于进程间共享内存至关重要。--gpus all 标志使容器内所有可用 GPU 都可访问，这对于需要 GPU 计算的任务至关重要。

注意：要在容器内处理本地机器上的文件，请使用 Docker 卷将本地目录挂载到容器中：

# 将本地目录挂载到容器内的目录
sudo docker run -it --ipc=host --gpus all -v /path/on/host:/path/in/container $t

将 /path/on/host 替换为本地机器上的目录路径，将 /path/in/container 替换为 Docker 容器内所需的访问路径。

对于高级 Docker 使用，欢迎探索 Ultralytics Docker 指南。

请参阅 ultralytics pyproject.toml 文件以获取依赖项列表。请注意，上述所有示例都安装了所有必需的依赖项。

Tip

PyTorch 的要求因操作系统和 CUDA 要求而异，因此建议首先按照 https://pytorch.org/get-started/locally 的说明安装 PyTorch。

PyTorch 安装说明

使用 CLI 使用 Ultralytics

Ultralytics 命令行界面（CLI）允许使用简单的单行命令，无需 Python 环境。CLI 不需要自定义或 Python 代码。您只需在终端中使用 yolo 命令即可运行所有任务。查看 CLI 指南 以了解更多关于从命令行使用 YOLO 的信息。

Example

Ultralytics yolo 命令使用以下语法： 

yolo TASK MODE ARGS

查看所有 ARGS 在完整的 配置指南 或使用 yolo cfg CLI 命令。

使用初始学习率为 0.01 训练一个检测模型 10 个 epochs 

yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01

使用预训练的分割模型在图像大小为 320 的情况下预测 YouTube 视频： 

yolo predict model=yolo11n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320

在批量大小为 1 和图像大小为 640 的情况下验证预训练的检测模型： 

yolo val model=yolo11n.pt data=coco8.yaml batch=1 imgsz=640

将 yolo11n 分类模型导出为 ONNX 格式，图像大小为 224x128（不需要 TASK） 

yolo export model=yolo11n-cls.pt format=onnx imgsz=224,128

运行特殊命令以查看版本、查看设置、运行检查等： 

yolo help
yolo checks
yolo version
yolo settings
yolo copy-cfg
yolo cfg

Warning

参数必须以 arg=val 对的形式传递，用等号 = 分隔，并用空格分隔对。不要使用 -- 参数前缀或在参数之间使用逗号 ,。

  • yolo predict model=yolo11n.pt imgsz=640 conf=0.25 ✅
  • yolo predict model yolo11n.pt imgsz 640 conf 0.25 ❌（缺少 =）
  • yolo predict model=yolo11n.pt, imgsz=640, conf=0.25 ❌（不要使用 ,）
  • yolo predict --model yolo11n.pt --imgsz 640 --conf 0.25 ❌（不要使用 --）

CLI 指南

使用 Python 使用 Ultralytics

YOLO 的 Python 接口允许无缝集成到您的 Python 项目中，使得加载、运行和处理模型的输出变得容易。设计时考虑到了简单性和易用性，Python 接口使用户能够快速在他们的项目中实现 目标检测、分割和分类。这使得 YOLO 的 Python 接口成为任何希望将这些功能集成到其 Python 项目中的人的宝贵工具。

例如，用户可以加载模型、训练它、在验证集上评估其性能，甚至只需几行代码即可将其导出为 ONNX 格式。查看 Python 指南 以了解更多关于在您的 Python 项目中使用 YOLO 的信息。

Example

from ultralytics import YOLO

# 从零开始创建一个新的 YOLO 模型
model = YOLO("yolo11n.yaml")

# 加载一个预训练的 YOLO 模型（推荐用于训练）
model = YOLO("yolo11n.pt")

# 使用 'coco8.yaml' 数据集训练模型 3 个 epoch
results = model.train(data="coco8.yaml", epochs=3)

# 在验证集上评估模型的性能
results = model.val()

# 使用模型对图像进行目标检测
results = model("https://ultralytics.com/images/bus.jpg")

# 将模型导出为 ONNX 格式
success = model.export(format="onnx")

Python 指南

Ultralytics 设置

Ultralytics 库提供了一个强大的设置管理系统，以实现对实验的精细控制。通过利用 ultralytics.utils 模块中的 SettingsManager，用户可以轻松访问和更改其设置。这些设置存储在环境用户配置目录中的 JSON 文件中，并且可以直接在 Python 环境中或通过命令行界面（CLI）查看或修改。

检查设置

要了解当前设置的配置情况，您可以直接查看它们：

查看设置

你可以使用 Python 来查看你的设置。首先从 ultralytics 模块中导入 settings 对象。使用以下命令打印并返回设置： 

from ultralytics import settings

# 查看所有设置
print(settings)

# 返回特定设置
value = settings["runs_dir"]

或者，命令行界面允许你使用简单的命令检查你的设置： 

yolo settings

修改设置

Ultralytics 允许用户轻松修改他们的设置。可以通过以下方式进行更改：

更新设置

在 Python 环境中，调用 settings 对象的 update 方法来更改你的设置： 

from ultralytics import settings

# 更新一个设置
settings.update({"runs_dir": "/path/to/runs"})

# 更新多个设置
settings.update({"runs_dir": "/path/to/runs", "tensorboard": False})

# 重置设置为默认值
settings.reset()

如果你更喜欢使用命令行界面，以下命令将允许你修改你的设置： 

# 更新一个设置
yolo settings runs_dir='/path/to/runs'

# 更新多个设置
yolo settings runs_dir='/path/to/runs' tensorboard=False

# 重置设置为默认值
yolo settings reset

理解设置

下表概述了可在 Ultralytics 中调整的设置。每个设置都列出了示例值、数据类型和简要描述。

名称 示例值 数据类型 描述
settings_version '0.0.4' str Ultralytics settings 版本（与 Ultralytics pip 版本不同）
datasets_dir '/path/to/datasets' str 存储数据集的目录
weights_dir '/path/to/weights' str 存储模型权重的目录
runs_dir '/path/to/runs' str 存储实验运行的目录
uuid 'a1b2c3d4' str 当前设置的唯一标识符
sync True bool 是否将分析和崩溃同步到 HUB
api_key '' str Ultralytics HUB API Key
clearml True bool 是否使用 ClearML 日志记录
comet True bool 是否使用 Comet ML 进行实验跟踪和可视化
dvc True bool 是否使用 DVC for experiment tracking 和版本控制
hub True bool 是否使用 Ultralytics HUB 集成
mlflow True bool 是否使用 MLFlow 进行实验跟踪
neptune True bool 是否使用 Neptune 进行实验跟踪
raytune True bool 是否使用 Ray Tune 进行 超参数调优
tensorboard True bool 是否使用 TensorBoard 进行可视化
wandb True bool 是否使用 Weights & Biases 日志记录
vscode_msg True bool 当检测到 VS Code 终端时，启用提示下载 Ultralytics-Snippets 扩展。

在浏览您的项目或实验时，请务必重新访问这些设置，以确保它们根据您的需求进行了最佳配置。

常见问题

如何使用 pip 安装 Ultralytics？

要使用 pip 安装 Ultralytics，请执行以下命令：

pip install ultralytics

对于最新的稳定版本，这将直接从 Python 包索引（PyPI）安装 ultralytics 包。更多详情，请访问 PyPI 上的 ultralytics 包。

或者，您可以直接从 GitHub 安装最新的开发版本：

pip install git+https://github.com/ultralytics/ultralytics.git

请确保您的系统上安装了 Git 命令行工具。

我可以使用 conda 安装 Ultralytics YOLO 吗？

是的，您可以通过运行以下命令使用 conda 安装 Ultralytics YOLO：

conda install -c conda-forge ultralytics

这种方法是 pip 的一个很好的替代方案，并确保与您环境中的其他包兼容。对于 CUDA 环境，最好同时安装 ultralytics、pytorch 和 pytorch-cuda 以解决任何冲突：

conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics

更多说明，请访问 Conda 快速入门指南。

使用 Docker 运行 Ultralytics YOLO 有什么优势？

使用 Docker 运行 Ultralytics YOLO 提供了一个隔离且一致的环境，确保在不同系统上的平稳性能。它还消除了本地安装的复杂性。Ultralytics 的官方 Docker 镜像可在 Docker Hub 上获取，有针对 GPU、CPU、ARM64、NVIDIA Jetson 和 Conda 环境的多种变体。以下是拉取和运行最新镜像的命令：

# 从 Docker Hub 拉取最新的 ultralytics 镜像
sudo docker pull ultralytics/ultralytics:latest

# 在支持 GPU 的容器中运行 ultralytics 镜像
sudo docker run -it --ipc=host --gpus all ultralytics/ultralytics:latest

更多详细的 Docker 说明，请查看 Docker 快速入门指南。

如何克隆 Ultralytics 仓库进行开发？

要克隆 Ultralytics 仓库并设置开发环境，请使用以下步骤：

# 克隆 ultralytics 仓库
git clone https://github.com/ultralytics/ultralytics

# 导航到克隆的目录
cd ultralytics

# 以可编辑模式安装包以进行开发
pip install -e .

这种方法允许您为项目做出贡献或使用最新的源代码进行实验。更多详情，请访问 Ultralytics GitHub 仓库。

为什么我应该使用 Ultralytics YOLO CLI？

Ultralytics YOLO 命令行界面（CLI）简化了无需 Python 代码即可运行对象检测任务的操作。您可以直接从终端执行单行命令进行训练、验证和预测等任务。yolo 命令的基本语法是：

yolo TASK MODE ARGS

例如，使用指定参数训练检测模型：

yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01

查看完整的 CLI 指南 以探索更多命令和使用示例。


📅 Created 11 months ago ✏️ Updated 14 days ago
glenn-jocher jk4e MatthewNoyce UltralyticsAssistant RizwanMunawar Burhan-Q Laughing-q AyushExel

Comments