安装 Ultralytics
Ultralytics 提供了多种安装方法,包括 pip、conda 和 Docker。您可以通过以下方式安装 YOLO: ultralytics
pip 软件包(用于最新的稳定版本),或通过克隆 Ultralytics GitHub 仓库 对于最新版本。Docker 也是一种在隔离容器中运行软件包的选项,这样可以避免本地安装。
观看: Ultralytics YOLO 快速入门指南
安装
安装或更新 ultralytics
通过运行以下命令,使用 pip 安装软件包 pip install -U ultralytics
。有关更多详细信息,请参阅 ultralytics
软件包,请访问 Python 包索引 (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 上找到。
# Install the ultralytics package using conda
conda install -c conda-forge ultralytics
注意
如果您在 CUDA 环境中安装,最佳实践是安装 ultralytics
, pytorch
和 pytorch-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
。
# 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 镜像,每个镜像都设计为具有高兼容性和效率:
- 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 文件以获取依赖项列表。请注意,以上所有示例都安装了所有必需的依赖项。
自定义安装方法
虽然标准的安装方法涵盖了大多数用例,但您可能需要更定制的设置。这可能涉及到安装特定的软件包版本,省略可选的依赖项,或者替换软件包,例如替换 opencv-python
使用无 GUI 的 opencv-python-headless
用于服务器环境。
自定义方法
您可以安装 ultralytics
使用 pip 的 package core,无需任何依赖项 --no-deps
标志。这需要您之后手动安装所有必要的依赖项。
-
安装
ultralytics
核心:pip install ultralytics --no-deps
-
手动安装依赖项: 您需要安装中列出的所有必需软件包
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 安装。
- Fork Ultralytics GitHub 存储库 到您自己的 GitHub 帐户。
- 克隆 您在本地的 fork:
git clone https://github.com/YOUR_USERNAME/ultralytics.git cd ultralytics
- 创建一个新分支 用于您的更改:
git checkout -b custom-opencv
- 修改
pyproject.toml
: 打开pyproject.toml
在文本编辑器中,替换包含以下内容的行"opencv-python>=4.6.0"
使用"opencv-python-headless>=4.6.0"
(根据需要调整版本)。 - 提交和推送 您的更改:
git add pyproject.toml git commit -m "Switch to opencv-python-headless" git push origin custom-opencv
- 安装 通过 pip 使用
git+https
语法,指向您的分支:pip install git+https://github.com/YOUR_USERNAME/ultralytics.git@custom-opencv
此方法确保在您从此特定 URL 安装时始终使用您的自定义依赖项集。有关在 a 中使用此方法的信息,请参见方法 4。 requirements.txt
文件。
与用于开发的标准“Git Clone”方法类似,您可以先在本地克隆存储库,在安装之前修改依赖文件,然后以可编辑模式安装。
- 克隆 Ultralytics 仓库:
git clone https://github.com/ultralytics/ultralytics cd ultralytics
- 修改
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>=..."
. - 安装 以可编辑模式安装包(
-e
)的副本。Pip 现在将使用您修改后的pyproject.toml
解决并安装依赖项:pip install -e .
在提交之前,此方法可用于测试对依赖项或构建配置的本地更改,或用于设置特定的开发环境。
如果您使用 a 管理您的项目依赖项 requirements.txt
文件中,您可以直接在其中指定您自定义的 Ultralytics 分支。这确保了任何设置项目的人都能获得您的特定版本及其修改后的依赖项(例如 opencv-python-headless
)。
- 创建或编辑
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
. - 安装 来自文件的依赖项:
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
)
通过 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")
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
, 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 --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 指南 中探索更多命令和使用示例。