安装 Ultralytics

安装或更新 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

# 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 --runtime=nvidia --gpus all $t            # all GPUs
sudo docker run -it --ipc=host --runtime=nvidia --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 --runtime=nvidia --gpus all $t            # all GPUs
sudo docker run -it --ipc=host --runtime=nvidia --gpus '"device=2,3"' $t # specify GPUs

上述命令使用最新的 ultralytics 镜像初始化一个 Docker 容器。 -it flags 分配一个伪 TTY 并保持 stdin 打开，从而允许与容器进行交互。该 --ipc=host 标志将 IPC（进程间通信）命名空间设置为 host，这对于进程之间共享内存至关重要。 --gpus all flag enables access to all available GPUs inside the container, crucial for tasks requiring GPU computation.

注意：要在容器中使用本地计算机上的文件，请使用 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 使用 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 ultralytics-thop
   
   # Install headless OpenCV instead of the default
   pip install opencv-python-headless
   

如果您需要持久的自定义修改（例如始终使用 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 源代码。

Ultralytics yolo 命令使用以下语法：

yolo TASK MODE ARGS

查看所有 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

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

from ultralytics import settings

# View all settings
print(settings)

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

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

yolo settings

在 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