在 GitHub 上编辑页面 (EN)

安装 Ultralytics

Ultralytics 提供了多种安装方式，包括 pip、conda 和 Docker。你可以通过 ultralytics pip 包安装 YOLO 以获取最新的稳定版本，或者通过克隆 Ultralytics GitHub 仓库 获取当前最新版本。Docker 也是一种选择，它可以在隔离的容器中运行该包，从而避免本地安装。



Watch: Ultralytics YOLO Quick Start Guide
安装

PyPI - Python Version

使用 pip 安装或更新 ultralytics 包，运行命令 pip install -U ultralytics。关于 ultralytics 包的更多详情，请访问 Python Package Index (PyPI)。

PyPI - Version Downloads

# Install or upgrade the ultralytics package from PyPI
pip install -U ultralytics

You can also install ultralytics directly from the Ultralytics GitHub repository. This can be useful if you want the latest development version. Ensure you have the Git command-line tool installed, and then run:

# Install the ultralytics package from GitHub
pip install git+https://github.com/ultralytics/ultralytics.git@main

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

提示

PyTorch 的要求因操作系统和 CUDA 要求而异，因此请先按照 PyTorch 上的说明安装 PyTorch。

PyTorch installation selector for different platforms

无头服务器安装

对于没有显示器的服务器环境（例如云虚拟机、Docker 容器、CI/CD 流水线），请使用 ultralytics-opencv-headless 包。它与标准 ultralytics 包完全相同，但依赖于 opencv-python-headless 而非 opencv-python，从而避免了不必要的 GUI 依赖项和潜在的 libGL 错误。

无头安装
pip install ultralytics-opencv-headless

两个包提供相同的功能和 API。无头变体只是排除了需要显示库的 OpenCV GUI 组件。

高级安装

虽然标准的安装方法涵盖了大多数使用场景，但你可能需要针对开发或自定义配置进行更定制化的设置。

高级方法

如果你需要持久的自定义修改，你可以 Fork Ultralytics 仓库，修改 pyproject.toml 或其他代码，然后从你的 Fork 进行安装。

  1. Fork Ultralytics GitHub 仓库 到你自己的 GitHub 账号。
  2. 克隆 你的 Fork 到本地： 
    git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
  3. 创建一个新分支 以保存你的修改： 
    git checkout -b my-custom-branch
  4. 进行修改 到 pyproject.toml 或根据需要修改其他文件。
  5. 提交并推送 你的修改： 
    git add .
git commit -m "My custom changes"
git push origin my-custom-branch
  6. 安装 使用带有 git+https 语法的 pip，指向你的分支： 
    pip install git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

将 Ultralytics 与 CLI 一起使用

Ultralytics 命令行界面 (CLI) 允许简单的单行命令，无需 Python 环境。CLI 不需要自定义或 Python 代码；使用 yolo 命令从终端运行所有任务。有关从命令行使用 YOLO 的更多信息，请参阅 CLI 指南。

示例

Ultralytics yolo 命令使用以下语法：

yolo TASK MODE ARGS

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

警告

参数必须作为 arg=value 对传递，由等号 = 分割并由空格分隔。不要在参数之间使用 -- 前缀或逗号 ,。

  • yolo predict model=yolo26n.pt imgsz=640 conf=0.25 ✅
  • yolo predict model yolo26n.pt imgsz 640 conf 0.25 ❌（缺少 =）
  • yolo predict model=yolo26n.pt, imgsz=640, conf=0.25 ❌（不要使用 ,）
  • yolo predict --model yolo26n.pt --imgsz 640 --conf 0.25 ❌（不要使用 --）
  • yolo solution model=yolo26n.pt imgsz=640 conf=0.25 ❌（使用 solutions，而不是 solution）

CLI 指南

将 Ultralytics 与 Python 一起使用

Ultralytics YOLO Python 接口提供与 Python 项目的无缝集成，使其能够轻松加载、运行和处理模型输出。Python 接口设计简洁，允许用户快速实现 对象检测、分割和分类。这使得 YOLO Python 接口成为将这些功能整合到 Python 项目中的宝贵工具。

例如，用户只需几行代码即可加载模型、进行训练、评估性能并将其导出为 ONNX 格式。浏览 Python 指南 以了解更多关于在 Python 项目中使用 YOLO 的信息。

示例
from ultralytics import YOLO

# Create a new YOLO model from scratch
model = YOLO("yolo26n.yaml")

# Load a pretrained YOLO model (recommended for training)
model = YOLO("yolo26n.pt")

# Train the model using the 'coco8.yaml' dataset for 3 epochs
results = model.train(data="coco8.yaml", epochs=3)

# Evaluate the model's performance on the validation set
results = model.val()

# Perform object detection on an image using the model
results = model("https://ultralytics.com/images/bus.jpg")

# Export the model to ONNX format
success = model.export(format="onnx")

Python 指南

Ultralytics 设置

Ultralytics 库包含一个 SettingsManager，用于对实验进行精细控制，允许用户轻松访问和修改设置。这些设置存储在环境用户配置目录下的 JSON 文件中，可以在 Python 环境中查看或修改，也可以通过命令行界面 (CLI) 进行操作。

检查设置

要查看当前的设置配置：

查看设置

Use Python to view your settings by importing the settings object from the ultralytics module. Print and return settings with these commands:

from ultralytics import settings

# View all settings
print(settings)

# Return a specific setting
value = settings["runs_dir"]

修改设置

Ultralytics 让你可以通过以下方式轻松修改设置：

更新设置

In Python, use the update method on the settings object:

from ultralytics import settings

# Update a setting
settings.update({"runs_dir": "/path/to/runs"})

# Update multiple settings
settings.update({"runs_dir": "/path/to/runs", "tensorboard": False})

# Reset settings to default values
settings.reset()

了解设置

下表概述了 Ultralytics 内的可调设置，包括示例值、数据类型和描述。

名称示例值数据类型描述
settings_version'0.0.4'strUltralytics settings version (distinct from the Ultralytics pip version)
datasets_dir'/path/to/datasets'str存储数据集的目录
weights_dir'/path/to/weights'str存储模型权重的目录
runs_dir'/path/to/runs'str存储实验运行的目录
uuid'a1b2c3d4'str当前设置的唯一标识符
syncTrueboolOption to sync analytics and crashes to Ultralytics Platform
api_key''strUltralytics Platform API Key
clearmlTrueboolOption to use ClearML logging
cometTrueboolOption to use Comet ML for experiment tracking and visualization
dvcTrueboolOption to use DVC for experiment tracking and version control
hubTrueboolOption to use Ultralytics Platform integration
mlflowTrueboolOption to use MLFlow for experiment tracking
neptuneTrueboolOption to use Neptune for experiment tracking
raytuneTrueboolOption to use Ray Tune for hyperparameter tuning
tensorboardTrueboolOption to use TensorBoard for visualization
wandbTrueboolOption to use Weights & Biases logging
vscode_msgTrueboolWhen a VS Code terminal is detected, enables a prompt to download the Ultralytics-Snippets extension.

随着项目的推进或实验的进行，请重新查看这些设置以确保配置最佳。

常见问题 (FAQ)

如何使用 pip 安装 Ultralytics？

使用 pip 安装 Ultralytics：

pip install -U ultralytics

This installs the latest stable release of the ultralytics package from PyPI. To install the development version directly from 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 提供了隔离且一致的环境，确保了在不同系统上的流畅性能，并避免了本地安装的复杂性。官方 Docker 镜像可在 Docker Hub 上获取，并提供针对 GPU、CPU、ARM64、NVIDIA Jetson 和 Conda 的变体。要拉取并运行最新镜像：

# Pull the latest ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

# Run the ultralytics image in a container with GPU support
sudo docker run -it --ipc=host --runtime=nvidia --gpus all ultralytics/ultralytics:latest

有关详细的 Docker 说明，请参阅 Docker 快速入门指南。

如何克隆 Ultralytics 存储库以进行开发？

克隆 Ultralytics 存储库并使用以下命令设置开发环境：

# Clone the ultralytics repository
git clone https://github.com/ultralytics/ultralytics

# Navigate to the cloned directory
cd ultralytics

# Install the package in editable mode for development
pip install -e .

这使你可以为项目做出贡献或使用最新的源代码进行实验。有关详细信息，请访问 Ultralytics GitHub 存储库。

为什么要使用 Ultralytics YOLO CLI？

Ultralytics YOLO CLI 简化了无需 Python 代码即可运行目标检测任务的过程，能够直接从你的终端通过单行命令进行训练、验证和预测。基本语法为：

yolo TASK MODE ARGS

例如，要训练一个检测模型：

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

在完整的 CLI 指南 中探索更多命令和使用示例。

Contributors
在 GitHub 上编辑页面 (EN)
GLglenn-jocher29RIRizwanMunawar6PDpderrenger3BUBurhan-Q3LALaughing-q2ONonuralpszr2JKjk4e2FCfcakyon1LAlakshanthad1PIpicsalex1LEleonnil1MAMatthewNoyce1

评论