> Table of Contents
> [TOC]

# YOLOv8 Tutorial

## Installing Anaconda

1. Download the installer from the [official Anaconda website](https://www.anaconda.com/download) to your computer.

:::success
**💡Tip**
- Please choose the appropriate installer based on your operating system.
- All versions provide a graphical user interface for installation.
:::

| Windows | Mac | Linux |
| :-----: | :-: | :---: |
| [Download](https://repo.anaconda.com/archive/Anaconda3-2024.10-1-Windows-x86_64.exe) | [Download](https://repo.anaconda.com/archive/Anaconda3-2024.10-1-MacOSX-arm64.pkg) | [Download](https://repo.anaconda.com/archive/Anaconda3-2024.10-1-Linux-x86_64.sh) |

---

## Setting Environment Variables

2. Search for `Environment Variables` in your system settings.
3. Click on `Environment Variables`.

4. Under **System Variables**, select `Path` and click **Edit**.

5. Click **New** and add the following environment variable paths:

:::spoiler Environment Variable Paths [Expand]

C:\ProgramData\Anaconda3
C:\ProgramData\Anaconda3\Script\Library\bin
C:\ProgramData\Anaconda3\Scripts
C:\ProgramData\Anaconda3\condabin

:::

## Creating a YOLOv8 Environment

6. Launch **Anaconda Navigator**.

7. At the bottom of the interface, click **Create** to add a new environment.

8. In the **Create New Environment** dialog, configure the environment as follows:
- **Name:** `YOLOv8`
- **Location:** `C:\User\Ryan\envs\YOLOv8`
(Replace `Ryan` with your actual Windows username if different)
- **Packages:** Python `3.10.16`

---

## Activating the YOLOv8 Environment

9. Select the newly created `YOLOv8` environment and click **Open Terminal**.

10. You should now see the terminal window for the environment.

:::spoiler Advanced Usage [Expand]
Steps `6~10` can be skipped by using the following commands:

> 1. Open **Windows Command Prompt** (in <font color=blue>Windows 11</font> it's renamed to **Windows Terminal**; we will refer to it as `Windows Command` here).
> 2. Create the environment with the following command:
> `conda create --name <environment_name> python=<python_version>`
> Example:
> ```bash
> conda create --name YOLOv8 python=3.10.16
> ```
> 

> 3. To activate the environment, use:
> ```bash
> conda activate YOLOv8
> ```
> 

> 4. Once the environment is activated successfully, your terminal should look like this:
> 

:::

## Installing NVIDIA Driver

### Installing the NVIDIA CUDA Toolkit

1. Download and install [CUDA Toolkit 11.8](https://developer.nvidia.com/cuda-11-8-0-download-archive).

> [!NOTE]
> Be sure to select the correct version of your operating system.
> This guide uses **Windows 11** as an example.

2. Go to the [cuDNN Archive](https://developer.nvidia.com/rdp/cudnn-archive) and download the version highlighted in the <font color=red>**red box**</font>.

---

### Installing NVIDIA cuDNN

1. Open the section titled `Download cuDNN v8.9.7 (December 5th, 2023), for CUDA 11.x`, and select the file as shown in the <font color=red>**red box**</font>.

2. You must sign in to your **NVIDIA Account** to download.
If you don’t have one, please register in a new tab.

3. After downloading, you will get the file:
`cudnn-windows-x86_64-8.9.7.29_cuda11-archive.zip`

4. Locate the following path:
`C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8`

5. Extract the contents of the ZIP file and copy the following folders into the CUDA directory above:
- `bin`
- `include`
- `lib`

These should be merged into the corresponding folders inside `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8`.

### Verifying the NVIDIA Driver Installation

- Open the **Windows Command Prompt** and type the following command to check if the GPU is detected by the driver:

nvidia-smi

If successful, you will see an output like the following:

- Then, enter the following command to confirm the CUDA compiler (`nvcc`) is properly installed:

nvcc -V


## Installing YOLOv8

1. First, download the required files: `7-Zip`, the `YOLOv8` repository, and the pretrained `YOLOv8n.pt` model.

:::warning
**😁 Reminder**
Please download the following files from the provided links before proceeding.
:::

- Download `7-Zip`: [Link](https://www.7-zip.org/a/7z2409-x64.exe)
- Clone or download the `YOLOv8` repository: [Link](https://github.com/Yucheng0208/YOLOv8)
- Download the `YOLOv8n.pt` model: [Link](https://github.com/ultralytics/assets/releases/download/v8.1.0/yolov8n.pt)

2. Install `7-Zip`.
To verify the installation, right-click on any file and check if the `7-Zip` menu appears as shown below:

3. Extract the `YOLOv8-main.zip` file using `7-Zip` or another archive tool.

4. After extraction, you may rename the folder to `YOLOv8` and place it in a directory of your choice.
For example:

:::info
**💡Tip**
In this tutorial, we use `D:\` as the example directory path.
:::

5. Move the `yolov8n.pt` model file into the `YOLOv8` folder.

6. In the command line inside the `YOLOv8` folder, run the following command to install the `Ultralytics` package:

pip install ultralytics

## Installing PyTorch

1. Visit the [official PyTorch website](https://pytorch.org/get-started/locally/) to find the appropriate version for your environment.

2. In the **Windows Command Prompt**, change the directory to your YOLOv8 project folder:

cd /d D:\YOLOv8

3. Install PyTorch using the following command:
:::danger
**🚨 Note**
Replace `pip3` with `pip`.
:::

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

4. If this version does not work for your system, visit the [Previous PyTorch Versions](https://pytorch.org/get-started/previous-versions/)page to find a suitable one.

## Development Environment

### Platform & Tools

| Component | Specification |
| :-------- | :------------ |
| Running environment | System: Windows 11 Pro, </br> CPU: Intel Core i9-12900K, </br> RAM: 16GB * 2 (32GB), </br> GPU: NVIDIA GeForce RTX 3090 |
| Visual Studio Code | Sep 2024 (version 1.94) |
| Environment management | Conda 24.9.0 |
| Python | Version 3.10.16 |

### Package Requirements
Use the following command to install all necessary packages.
Ensure the environment matches exactly before using `requirements.txt`.

:::spoiler requirements.txt [Expand]

beautifulsoup4==4.12.3
certifi==2024.12.14
charset-normalizer==3.4.1
colorama==0.4.6
contourpy==1.3.1
cycler==0.12.1
filelock==3.13.1
fonttools==4.55.3
fsspec==2024.2.0
idna==3.10
Jinja2==3.1.3
kiwisolver==1.4.8
labelImg==1.8.6
lxml==5.3.0
MarkupSafe==2.1.5
matplotlib==3.10.0
mpmath==1.3.0
networkx==3.2.1
numpy==1.26.3
opencv-python==4.11.0.86
packaging==24.2
pandas==2.2.3
pillow==10.2.0
psutil==6.1.1
py-cpuinfo==9.0.0
pyparsing==3.2.1
PyQt5==5.15.11
PyQt5-Qt5==5.15.2
PyQt5_sip==12.16.1
python-dateutil==2.9.0.post0
pytz==2024.2
PyYAML==6.0.2
requests==2.32.3
scipy==1.15.1
seaborn==0.13.2
six==1.17.0
soupsieve==2.6
sympy==1.13.1
torch==2.5.1+cu118
torchaudio==2.5.1+cu118
torchvision==0.20.1+cu118
tqdm==4.67.1
typing_extensions==4.9.0
tzdata==2024.2
ultralytics==8.3.64
ultralytics-thop==2.0.14
urllib3==2.3.0

:::

## Dataset Preprocessing

### Batch Video Converter

For converting videos recorded from various platforms (Windows, iOS, Android) into a unified MP4 format, use the [Batch-Video-Converter](https://github.com/Yucheng0208/Batch-Video-Converter) tool.

1. Unzip `Batch-Video-Converter-main.zip` and rename the folder to `Batch-Video-Converter`.

2. When prompted with `Enter the input directory containing videos:`, enter the path of the folder containing the videos to convert.

3. When prompted with `Enter the output directory for converted MP4 videos:`, enter the desired output path.
- If left blank, a folder named `output` will be created inside the input directory.

4. When asked `Do you want to keep audio in the converted videos? (Y/N, default: N):`, input `Y` to retain audio, or `N` to remove it (default is `N`).

---

### Video Frame Extractor

To simplify the labeling process for beginners, [Video-Frame-Extractor](https://github.com/Yucheng0208/Video-Frame-Extractor) helps convert videos into image sequences.

1. Download and unzip the archive, then rename the folder to `Video-Frame-Extractor`.

2. Run the extractor:

python Video-Frame-Extractor.py

3. You'll be prompted to enter:
- The input video directory
- The output frame directory
- The frame rate (e.g., `60` FPS is common)

4. The extractor will process all videos in the folder and output numbered image frames starting from `0`.

### Labelimg Annotation Tool

1. Install the tool

pip install labelimg

2. Download [labelimg](https://github.com/Yucheng0208/labelImg), unzip the archive, and rename the folder to `labelimg`.
3. Navigate into the folder:

cd labelimg

4. Launch the application:

python labelimg.py

5. The following window should appear:
6. Use **Open Dir** to label images in a folder or **Open File** for a single image.
7. After opening the folder, thumbnails appear in the bottom right, and the current image appears in the center.
8. In the top-left menu, enable **Auto Save Mode** under the View (V) tab.
9. Set the annotation mode to **YOLO format**.
10. Click **Create RectBox** to start labeling.
11. Use the cursor (displayed as a cross) to draw bounding boxes.
12. For custom labels like `Helmet` or `Coverall`, manually enter and confirm them.

:::danger
**🚨 Note**
You must finish labeling **all objects in one image** before moving to the next. You cannot return to previous images.
:::

13. All labeled items will appear in the box list on the right side.

:::success
**📌 Pro Tip**
- Path: `D:\labelImg\data`。
- File: `predefined_classes.txt`。
- Add label names to this file for quick label access during annotation.
:::

14. Once labeling is done, click **Next Image**.
15. In the terminal, you will see lines like:

Image:C:\Users\Ryan\Desktop\output\frame_0000.png -> Annotation:frame_0000.txt

This means `frame_0000.png` was labeled and saved as `frame_0000.txt`.
16. You are now in “Annotation Mode”! Already used labels will auto-complete from the menu.

:::info
**🌐 Resources**
For public datasets, consider [RoboFlow 官網](https://roboflow.com/) and [Kaggle 官網](https://www.kaggle.com/). Be sure to cite original authors.
:::

## Using YOLOv8

**🔍 Basic Prediction Test**

Run the following command to test the model with a sample image:

yolo predict model=yolov8m.pt source='https://ultralytics.com/images/bus.jpg'

:::spoiler Dataset Structure [Expand]
YOLOv8
└─dataset
│ ├─test
│ │ ├─images
│ │ │ ├─test_img001.jpg
│ │ │ ├─test_img002.jpeg
│ │ │ ├─test_img003.png
│ │ │ └─test_img004.tif
│ │ └─labels
│ │ ├─test_img001.txt
│ │ ├─test_img002.txt
│ │ ├─test_img003.txt
│ │ └─test_img004.txt
│ ├─train
│ │ ├─images
│ │ │ ├─train_img001.jpg
│ │ │ ├─train_img002.jpeg
│ │ │ ├─train_img003.png
│ │ │ └─train_img004.tif
│ │ └─labels
│ │ ├─train_img001.txt
│ │ ├─train_img002.txt
│ │ ├─train_img003.txt
│ │ └─train_img004.txt
│ └─valid
│ ├─images
│ │ ├─valid_img001.jpg
│ │ ├─valid_img002.jpeg
│ │ ├─valid_img003.png
│ │ └─valid_img004.tif
│ └─labels
│ ├─valid_img001.txt
│ ├─valid_img002.txt
│ ├─valid_img003.txt
│ └─valid_img004.txt
└─data.yaml
:::

### Training YOLOv8 with Custom Dataset

#### 1. Create the `data.yaml` File
Inside your `YOLOv8` directory, create a file named `data.yaml`.
Example structure:

train: dataset/train
val: dataset/val
test: dataset/test

nc: 2
names: ['Helmet', 'Coverall']

**📝 Parameter Descriptions**

- `train`: Path to the training set.
- `val`: Path to the validation set.
- `test`: Path to the test set.
- `nc` : Number of classes.
- `names`: Class names in order.`0 `corresponds to `Helmet`, `1` to `Coverall`.

#### 2. Check Your Label Format
A label file (`frame_0000.txt`) may look like this:

15 0.402734 0.114583 0.099219 0.159722
16 0.417969 0.538889 0.178125 0.744444

:::info
**📝 Explanation**
- The `first` value is the class ID (e.g., `16`, `15`).
- The next four values represent normalized bounding box coordinates:
`<x_center> <y_center> <width> <height>`
If your label class IDs are not 0 and 1, you can use the [YOLO-Class-ID-Replacer](https://github.com/Yucheng0208/YOLO-Class-ID-Replacer) to remap them:

# Class ID mapping example
class_id_mapping = {
    "15": "0",  # Map class 15 to 0
    "16": "1",  # Map class 16 to 1
}

:::

#### 3. Start Training
Use the following command to begin training:

yolo detect train data=data.yaml model=yolov8n.pt epochs=100 imgsz=640 conf=0 device=0

**Training Logs**
YOLOv8 will:
- Scan your `train`, `val`, and `test` folders
- Display GPU and dataset configuration
- Start training from 1/100 to 100/100 epochs

**📝 Training Metrics**
- `Epoch`: Current training round.
- `GPU mem`: GPU memory usage.
- `box loss`: Bounding box regression loss.
- `cls loss`: Classification loss.
- `dfl loss`: Distribution focal loss (YOLOv8-specific).
- `Instances`: Number of objects processed in current batch.

**📝 Validation Metrics**
- `Size`: Input image size.
- `Class`: Number of detected classes.
- `Images`: Number of images in validation batch.
- `Box (P)`: Precision score.
- `R`: Recall score.
- `mAP50`: Mean Average Precision at IoU 0.50.
- `mAP50-95`: Average precision across IoU thresholds from 0.50 to 0.95.

### Model Checkpoints
After training, two model files will be generated:

**💭 Model Descriptions**
- `best.pt`:
The model checkpoint with the highest performance on the validation set.
Use this for final prediction or deployment.
- `last.pt`:
The checkpoint from the final epoch. Useful for further fine-tuning, not necessarily the best performing.

#### 4. Run Inference with Custom Model
Use the trained model to make predictions:

yolo detect predict model=best.pt epochs=100 imgsz=640 conf=0 device=0 source=0 save=True show=True

**📝 Inference Parameters Explained**
1. `model`: Path to model checkpoint
- Use pre-trained (yolov8n.pt) or your custom model (`best.pt` or `last.pt`)
2. `epochs`: Epoch count for further training (ignored in prediction mode)
3. `imgsz`: Image resolution (e.g., `640`, `1280`)
4. `conf`: Confidence threshold
- `conf=0.25` will filter out predictions below 25% confidence.
5. `device`: Device to use for prediction
- `0` = first GPU, `cpu` = CPU, `mps` = Apple Silicon GPU
6. `source`: Input source
- `0` = webcam
- `images/sample.jpg` = single image
- `videos/sample.mp4` = video file
- Folder path or livestream URL also accepted.
7. `save`: Whether to save output `images/videos`
- `True` = save output to `/runs/`
- `False` = do not save
8. `show`: Display results in a pop-up window
- `True` = show prediction
- `False` = headless mode

# Development Log
This YOLOv8 tutorial and deployment guide was authored and refined by Yu-Cheng Chang (張育丞), as part of a structured effort to document the full setup, training, and inference process of an object detection system using Ultralytics YOLOv8.

The motivation behind this guide stems from real-world needs in dataset preprocessing, efficient model training, and reproducible development pipelines. The tutorial was developed in an engineering-research context, especially focusing on:

- **⚙️ Cross-platform setup** (Windows 11)
- **🐍 Environment isolation** using Conda
- **🧠 Deep learning framework** installation including CUDA, cuDNN, and PyTorch (GPU acceleration enabled)
- **📦 Ultralytics YOLOv8 usage**, from simple prediction to full dataset training
- **📽️ Dataset tools**:
- [Batch-Video-Converter for MOV/WMV](https://github.com/Yucheng0208/Batch-Video-Converter) to MP4 conversion
- [Video-Frame-Extractor](https://github.com/Yucheng0208/Video-Frame-Extractor) for extracting frames from video at a desired FPS
- [labelImg](https://github.com/Yucheng0208/Video-Frame-Extractor) with detailed annotation instructions for YOLO format
- **🧾 Model class remapping using** [YOLO-Class-ID-Replacer](https://github.com/Yucheng0208/YOLO-Class-ID-Replacer)
The entire tutorial has been written in both Chinese (for HackMD and local use) and translated into clean, professional English Markdown format for GitHub sharing and open-source collaboration.
The teaching structure was organized progressively to ensure that students, researchers, and developers could:
1. Follow step-by-step instructions without missing key environment issues.
2. Understand practical training parameters and their meanings.
3. Deploy and test models with confidence on real-time data.

> This document serves not only as technical guidance but also as a reproducible lab notebook — one that balances accessibility and precision.

## Update History
| Version | Date | Description |
|-----------|-------------|----------------------------------------------|
| 1.0 | Jan 01, 2025 | Initial draft created |
| 2.0 | Jan 15, 2025 | Added CUDA and cuDNN setup instructions |
| 3.0 | Jan 20, 2025 | Integrated video conversion pipeline |
| 3.1 | Jan 22, 2025 | Updated video frame extraction documentation |
| 4.0 | Jan 26, 2025 | Added labeling tool (labelImg) tutorial |
| 5.0 | Feb 03, 2025 | Integrated YOLOv8 training guide |
| 5.1 | Feb 17, 2025 | Added `YOLO-Class-ID-Replacer` explanation |
| 6.0 | Mar 07, 2025 | Organized complete data.yaml usage details |
| 6.1 | Mar 22, 2025 | Revised training metrics and evaluation logs |
| 7.0 | Apr 16, 2025 | Added inference demo and explanation |
| 8.0 | May 04, 2025 | Finalized English version for GitHub release |

# Citation

@article{chang2025yolov8tutorial,
  title     = {YOLOv8 Tutorial},
  author    = {Yu-Cheng Chang},
  journal   = {HackMD},
  year      = {2025},
  url       = {https://hackmd.io/@Yucheng208/YOLOv8-Tutorial}
}

# License

This content is licensed under the `MIT License`. See the LICENSE for details.

MIT License

Copyright (c) 2025 Yu-Cheng, Chang

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

# Contributing
Contributions or feedback are welcome!
Please feel free to contact me via [email](mailto:[e-mail]) for any suggestions or inquiries.