Quickstart

Install the ultralytics package using pip, or update an existing installation by running pip install -U ultralytics. Visit the Python Package Index (PyPI) for more details on the ultralytics package: https://pypi.org/project/ultralytics/.

# Install the ultralytics package from PyPI
pip install ultralytics

You can also install the ultralytics package directly from the GitHub repository. This might be useful if you want the latest development version. Make sure to have the Git command-line tool installed on your system. The @main command installs the main branch and may be modified to another branch, i.e. @my-branch, or removed entirely to default to main branch.

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

Conda is an alternative package manager to pip which may also be used for installation. Visit Anaconda for more details at https://anaconda.org/conda-forge/ultralytics. Ultralytics feedstock repository for updating the conda package is at https://github.com/conda-forge/ultralytics-feedstock/.

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

Ultralytics Conda Docker images are also available from DockerHub. These images are based on Miniconda3 and are an simple way to start using ultralytics in a Conda environment.

# 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

Clone the ultralytics repository if you are interested in contributing to the development or wish to experiment with the latest source code. After cloning, navigate into the directory and install the package in editable mode -e using pip.

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

Utilize Docker to effortlessly execute the ultralytics package in an isolated container, ensuring consistent and smooth performance across various environments. By choosing one of the official ultralytics images from Docker Hub, you not only avoid the complexity of local installation but also benefit from access to a verified working environment. Ultralytics offers 5 main supported Docker images, each designed to provide high compatibility and efficiency for different platforms and use cases:

• Dockerfile: GPU image recommended for training.
• Dockerfile-arm64: Optimized for ARM64 architecture, allowing deployment on devices like Raspberry Pi and other ARM64-based platforms.
• Dockerfile-cpu: Ubuntu-based CPU-only version suitable for inference and environments without GPUs.
• Dockerfile-jetson: Tailored for NVIDIA Jetson devices, integrating GPU support optimized for these platforms.
• Dockerfile-python: Minimal image with just Python and necessary dependencies, ideal for lightweight applications and development.
• Dockerfile-conda: Based on Miniconda3 with conda installation of ultralytics package.

Below are the commands to get the latest image and execute it:

# 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

The above command initializes a Docker container with the latest ultralytics image. The -it flag assigns a pseudo-TTY and maintains stdin open, enabling you to interact with the container. The --ipc=host flag sets the IPC (Inter-Process Communication) namespace to the host, which is essential for sharing memory between processes. The --gpus all flag enables access to all available GPUs inside the container, which is crucial for tasks that require GPU computation.

Note: To work with files on your local machine within the container, use Docker volumes for mounting a local directory into the container:

# 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

Alter /path/on/host with the directory path on your local machine, and /path/in/container with the desired path inside the Docker container for accessibility.

For advanced Docker usage, feel free to explore the Ultralytics Docker Guide.

Ultralytics yolo commands use the following syntax:

yolo TASK MODE ARGS

• TASK (optional) is one of (detect, segment, classify, pose)
• MODE (required) is one of (train, val, predict, export, track)
• ARGS (optional) are arg=value pairs like imgsz=640 that override defaults.

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

Train a detection model for 10 epochs with an initial learning_rate of 0.01

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

Predict a YouTube video using a pretrained segmentation model at image size 320:

yolo predict model=yolov8n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320

Val a pretrained detection model at batch-size 1 and image size 640:

yolo val model=yolov8n.pt data=coco8.yaml batch=1 imgsz=640

Export a YOLOv8n classification model to ONNX format at image size 224 by 128 (no TASK required)

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

Run special commands to see version, view settings, run checks and more:

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

You can use Python to view your settings. Start by importing the settings object from the ultralytics module. Print and return settings using the following commands:

from ultralytics import settings

# View all settings
print(settings)

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

Alternatively, the command-line interface allows you to check your settings with a simple command:

yolo settings

Within the Python environment, call the update method on the settings object to change your 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()

If you prefer using the command-line interface, the following commands will allow you to modify your settings:

# 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