跳转至内容

安装 Ultralytics

Ultralytics 提供了多种安装方法,包括 pip、conda 和 Docker。您可以通过以下方式安装 YOLO: ultralytics pip 软件包(用于最新的稳定版本),或通过克隆 Ultralytics GitHub 仓库 对于最新版本。Docker 也是一种在隔离容器中运行软件包的选项,这样可以避免本地安装。



观看: Ultralytics YOLO 快速入门指南

安装

PyPI - python 版本

安装或更新 ultralytics 通过运行以下命令,使用 pip 安装软件包 pip install -U ultralytics。有关更多详细信息,请参阅 ultralytics 软件包,请访问 Python 包索引 (PyPI).

PyPI - 版本 下载

# Install the ultralytics package from PyPI
pip install ultralytics

您也可以安装 ultralytics 直接从 Ultralytics GitHub 仓库。如果您想要最新的开发版本,这将非常有用。确保您已安装 Git 命令行工具,然后运行:

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

Conda 可以用作 pip 的替代包管理器。有关更多详细信息,请访问 Anaconda。用于更新 conda 软件包的 Ultralytics feedstock 存储库可在 GitHub 上找到。

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

# Install the ultralytics package using conda
conda install -c conda-forge ultralytics

注意

如果您在 CUDA 环境中安装,最佳实践是安装 ultralytics, pytorchpytorch-cuda 在同一命令中。这允许 conda 包管理器解决任何冲突。或者,安装 pytorch-cuda 最后覆盖 CPU 相关的 pytorch 包(如果必要)。

# Install all packages together using conda
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics

Conda Docker 镜像

Ultralytics Conda Docker 镜像也可从 DockerHub获取。这些镜像基于 Miniconda3 并提供了一种开始使用的直接方法 ultralytics 的简单方法。

# Set image name as a variable
t=ultralytics/ultralytics:latest-conda

# Pull the latest ultralytics image from Docker Hub
sudo docker pull $t

# Run the ultralytics image in a container with GPU support
sudo docker run -it --ipc=host --gpus all $t            # all GPUs
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t # specify GPUs

克隆 Ultralytics GitHub 仓库 如果您有兴趣为开发做贡献或希望尝试最新的源代码。克隆后,导航到该目录并将软件包以可编辑模式安装 -e

GitHub 最新提交 GitHub 提交活跃度

# 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 .

使用 Docker 执行 ultralytics 以隔离容器中的软件包形式存在,确保在各种环境中性能一致。通过选择官方的 ultralytics Docker Hub 选择官方,您可以避免本地安装的复杂性,并获得经过验证的工作环境。Ultralytics 提供五个主要支持的 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 软件包。

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

# Set image name as a variable
t=ultralytics/ultralytics:latest

# Pull the latest ultralytics image from Docker Hub
sudo docker pull $t

# Run the ultralytics image in a container with GPU support
sudo docker run -it --ipc=host --gpus all $t            # all GPUs
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t # specify GPUs

上述命令使用最新的 ultralytics 镜像初始化一个 Docker 容器。 -it flags 分配一个伪 TTY 并保持 stdin 打开,从而允许与容器进行交互。该 --ipc=host 标志将 IPC(进程间通信)命名空间设置为 host,这对于进程之间共享内存至关重要。 --gpus all flag 允许访问容器内所有可用的 GPU,这对于需要 GPU 计算的任务至关重要。

注意:要在容器中使用本地计算机上的文件,请使用 Docker 卷将本地目录挂载到容器中:

# Mount local directory to a directory inside the container
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 文件以获取依赖项列表。请注意,以上所有示例都安装了所有必需的依赖项。

提示

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

PyTorch 安装说明

自定义安装方法

虽然标准的安装方法涵盖了大多数用例,但您可能需要更定制的设置。这可能涉及到安装特定的软件包版本,省略可选的依赖项,或者替换软件包,例如替换 opencv-python 使用无 GUI 的 opencv-python-headless 用于服务器环境。

自定义方法

您可以安装 ultralytics 使用 pip 的 package core,无需任何依赖项 --no-deps 标志。这需要您之后手动安装所有必要的依赖项。

  1. 安装 ultralytics 核心:

    pip install ultralytics --no-deps
    

  2. 手动安装依赖项: 您需要安装中列出的所有必需软件包 pyproject.toml 文件,根据需要替换或修改版本。对于无头 OpenCV 示例:

    # Install other core dependencies
    pip install torch torchvision numpy matplotlib polars pyyaml pillow psutil requests scipy seaborn ultralytics-thop
    
    # Install headless OpenCV instead of the default
    pip install opencv-python-headless
    

依赖管理

此方法提供完全控制,但需要仔细管理依赖项。通过参考以下内容,确保所有必需的软件包都安装了兼容的版本: ultralytics pyproject.toml 文件。

如果您需要持久的自定义修改(例如始终使用 opencv-python-headless),您可以 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 custom-opencv
    
  4. 修改 pyproject.toml: 打开 pyproject.toml 在文本编辑器中,替换包含以下内容的行 "opencv-python>=4.6.0" 使用 "opencv-python-headless>=4.6.0" (根据需要调整版本)。
  5. 提交和推送 您的更改:
    git add pyproject.toml
    git commit -m "Switch to opencv-python-headless"
    git push origin custom-opencv
    
  6. 安装 通过 pip 使用 git+https 语法,指向您的分支:
    pip install git+https://github.com/YOUR_USERNAME/ultralytics.git@custom-opencv
    

此方法确保在您从此特定 URL 安装时始终使用您的自定义依赖项集。有关在 a 中使用此方法的信息,请参见方法 4。 requirements.txt 文件。

与用于开发的标准“Git Clone”方法类似,您可以先在本地克隆存储库,安装之前修改依赖文件,然后以可编辑模式安装。

  1. 克隆 Ultralytics 仓库:
    git clone https://github.com/ultralytics/ultralytics
    cd ultralytics
    
  2. 修改 pyproject.toml: 编辑文件以进行所需的更改。例如,使用 sed (在 Linux/macOS 上)或使用文本编辑器替换 opencv-python 使用 opencv-python-headless. 使用 sed (验证以下行中的确切行 pyproject.toml 第一):
    # Example: Replace the line starting with "opencv-python..."
    # Adapt the pattern carefully based on the current file content
    sed -i'' -e 's/^\s*"opencv-python>=.*",/"opencv-python-headless>=4.8.0",/' pyproject.toml
    
    或手动编辑 pyproject.toml 要更改 "opencv-python>=..."opencv-python-headless>=...".
  3. 安装 以可编辑模式安装包(-e)的副本。Pip 现在将使用您修改后的 pyproject.toml 解决并安装依赖项:
    pip install -e .
    

在提交之前,此方法可用于测试对依赖项或构建配置的本地更改,或用于设置特定的开发环境。

如果您使用 a 管理您的项目依赖项 requirements.txt 文件中,您可以直接在其中指定您自定义的 Ultralytics 分支。这确保了任何设置项目的人都能获得您的特定版本及其修改后的依赖项(例如 opencv-python-headless)。

  1. 创建或编辑 requirements.txt: 添加一行指向您的自定义 fork 和分支(如方法 2 中准备的那样)。
    requirements.txt
    # Core dependencies
    numpy
    matplotlib
    polars
    pyyaml
    Pillow
    psutil
    requests>=2.23.0
    torch>=1.8.0 # Or specific version/variant
    torchvision>=0.9.0 # Or specific version/variant
    
    # Install ultralytics from a specific git commit or branch
    # Replace YOUR_USERNAME and custom-branch with your details
    git+https://github.com/YOUR_USERNAME/ultralytics.git@custom-branch
    
    # Other project dependencies
    flask
    # ... etc
    
    注意:您无需列出自定义所需依赖项中已有的依赖项 ultralytics 派生(如 opencv-python-headless)此处,因为 pip 将根据 fork 的 pyproject.toml.
  2. 安装 来自文件的依赖项:
    pip install -r requirements.txt
    

此方法与标准的 Python 项目依赖管理工作流程无缝集成,同时允许您固定 ultralytics 到您自定义的 Git 源代码。

通过 CLI 使用 Ultralytics

Ultralytics 命令行界面 (CLI) 允许简单的单行命令,而无需 Python 环境。CLI 不需要定制或 Python 代码;使用以下命令从终端运行所有任务 yolo 命令。有关从命令行使用 YOLO 的更多信息,请参见 CLI 指南.

示例

Ultralytics yolo 命令使用以下语法:

yolo TASK MODE ARGS
- TASK (可选)是以下之一(detect, 分割, 分类, 姿势估计, 旋转框检测) - MODE (必需)是以下之一(train, val, 预测, 导出, 追踪, 基准测试) - ARGS (可选)是 arg=value 键值对,例如 imgsz=640 用于覆盖默认值。

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

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

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

将 YOLOv11n 分类模型导出为 ONNX 格式,图像大小为 224x128(无需 TASK):

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

使用 YOLO11 统计视频或直播流中的物体数量:

yolo solutions count show=True

yolo solutions count source="path/to/video.mp4" # specify video file path

使用 YOLO11 姿势估计模型监控锻炼动作:

yolo solutions workout show=True

yolo solutions workout source="path/to/video.mp4" # specify video file path

# Use keypoints for ab-workouts
yolo solutions workout kpts="[5, 11, 13]" # left side
yolo solutions workout kpts="[6, 12, 14]" # right side

使用 YOLO11 来计算指定队列或区域中的对象:

yolo solutions queue show=True

yolo solutions queue source="path/to/video.mp4" # specify video file path

yolo solutions queue region="[(20, 400), (1080, 400), (1080, 360), (20, 360)]" # configure queue coordinates

使用 Streamlit 在 Web 浏览器中执行对象检测、实例分割或姿势估计:

yolo solutions inference

yolo solutions inference model="path/to/model.pt" # use model fine-tuned with Ultralytics Python package

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

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

警告

参数必须以 arg=value 键值对形式传递,用等号分隔 = 签名并用空格分隔。请勿使用 -- 参数前缀或逗号 , 在参数之间。

  • 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 ❌ (请勿使用 --)
  • yolo solution model=yolo11n.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("yolo11n.yaml")

# Load a pretrained YOLO model (recommended for training)
model = YOLO("yolo11n.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) 查看或修改。

查看设置

要查看当前设置的配置:

查看设置

使用 python 导入 settings 模块导入 ultralytics 模块。使用以下命令打印并返回设置:

from ultralytics import settings

# View all settings
print(settings)

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

命令行界面允许您使用以下命令检查您的设置:

yolo settings

修改设置

Ultralytics 可以通过以下方式轻松修改设置:

更新设置

在 python 中,使用 update 上的 settings 对象:

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()

要使用命令行界面修改设置:

# Update a setting
yolo settings runs_dir='/path/to/runs'

# Update multiple settings
yolo settings runs_dir='/path/to/runs' tensorboard=False

# Reset settings to default values
yolo settings reset

设置详解

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

名称 示例值 数据类型 描述
settings_version '0.0.4' str Ultralytics 设置版本(不同于 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 可选择将分析和崩溃同步到 Ultralytics HUB
api_key '' str Ultralytics HUB API 密钥
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 日志记录
vscode_msg True bool 当检测到 VS Code 终端时,会启用一个提示以下载 Ultralytics-Snippets 扩展。

随着项目的进展或实验的进行,重新审视这些设置,以确保最佳配置。

常见问题

如何使用 pip 安装 Ultralytics?

使用 pip 安装 Ultralytics:

pip install ultralytics

这将安装最新稳定版本的 ultralytics 来自软件包 PyPI。要直接从 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, pytorchpytorch-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 --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=yolo11n.pt epochs=10 lr0=0.01

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



📅 1 年前创建 ✏️ 5 天前更新

评论