快速开始

安装Ultralytics

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

安装

Pip安装（推荐）Conda安装Git克隆Docker

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

# 从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。用于更新conda包的Ultralytics feedstock仓库位于https://github.com/conda-forge/ultralytics-feedstock/。

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

注意

如果你在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安装包。

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

# 导航到克隆的目录
cd ultralytics

# 为开发安装可编辑模式下的包
pip install -e .

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

Dockerfile： 推荐用于训练的GPU映像。
Dockerfile-arm64： 为ARM64架构优化，允许在树莓派和其他基于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的requirements.txt文件。请注意，上述所有示例均安装了所有必需的依赖项。

Watch: Ultralytics YOLO Quick Start Guide

提示

PyTorch的要求因操作系统和CUDA需要而异，因此建议首先根据https://pytorch.org/get-started/locally上的指南安装PyTorch。

通过CLI使用Ultralytics

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

示例

语法训练预测验证导出特殊

Ultralytics yolo命令使用以下语法：

yolo 任务 模式 参数

其中   任务（可选）是[detect, segment, classify]中的一个
        模式（必需）是[train, val, predict, export, track]中的一个
        参数（可选）是任意数量的自定义“arg=value”对，如“imgsz=320”，可覆盖默认值。

在完整的配置指南中查看所有参数，或者用yolo cfg查看

用初始学习率0.01训练检测模型10个周期

yolo train data=coco128.yaml model=yolov8n.pt epochs=10 lr0=0.01

使用预训练的分割模型以320的图像大小预测YouTube视频：

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

以批量大小1和640的图像大小验证预训练的检测模型：

yolo val model=yolov8n.pt data=coco128.yaml batch=1 imgsz=640

以224x128的图像大小将YOLOv8n分类模型导出到ONNX格式（无需任务）

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

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

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

警告

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

yolo predict model=yolov8n.pt imgsz=640 conf=0.25 ✅
yolo predict model yolov8n.pt imgsz 640 conf 0.25 ❌
yolo predict --model yolov8n.pt --imgsz 640 --conf 0.25 ❌

CLI指南

通过Python使用Ultralytics

YOLOv8的Python接口允许无缝集成进您的Python项目，轻松加载、运行模型及处理输出。Python接口设计简洁易用，使用户能快速实现他们项目中的目标检测、分割和分类功能。这使YOLOv8的Python接口成为任何希望在其Python项目中纳入这些功能的人的宝贵工具。

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

示例

from ultralytics import YOLO

# 从头开始创建一个新的YOLO模型
model = YOLO('yolov8n.yaml')

# 加载预训练的YOLO模型（推荐用于训练）
model = YOLO('yolov8n.pt')

# 使用“coco128.yaml”数据集训练模型3个周期
results = model.train(data='coco128.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，用户可以轻松访问和修改设置。这些设置存储在YAML文件中，可以直接在Python环境中查看或修改，或者通过命令行界面(CLI)修改。

检查设置

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

查看设置

PythonCLI

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

from ultralytics import settings

# 查看所有设置
print(settings)

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

或者，命令行界面允许您用一个简单的命令检查您的设置：

yolo settings

修改设置

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

更新设置

PythonCLI

在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进行实验跟踪和版本控制
`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记录

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

Created 2023-11-12, Updated 2023-11-25
Authors: glenn-jocher (5), chr043416@gmail.com (1)