在 GitHub 上编辑页面 (EN)

安装 Ultralytics

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



Watch: Ultralytics YOLO Quick Start Guide
安装

PyPI - Python 版本

Install or update the ultralytics package using pip by running pip install -U ultralytics. For more details on the ultralytics package, visit the Python Package Index (PyPI).

PyPI - 版本 下载量

# 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 或其他代码进行更改，然后从你的分支进行安装。

  1. Fork Ultralytics GitHub 仓库 到你自己的 GitHub 账号。
  2. Clone 你的分支到本地： 
    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

在 CLI 中使用 Ultralytics

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

示例

Ultralytics yolo 命令使用以下语法：

yolo TASK MODE ARGS

See all ARGS in the full Configuration Guide or with the yolo cfg CLI command.

警告

参数必须以 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 指南

在 Python 中使用 Ultralytics

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-jocher30RIRizwanMunawar6LALaughing-q3PDpderrenger3BUBurhan-Q3ONonuralpszr2JKjk4e2FCfcakyon1LAlakshanthad1PIpicsalex1LEleonnil1MAMatthewNoyce1

评论