Darknet Object Detection Framework and YOLO
!darknet and hank.ai logos
Darknet is an open-source neural network framework written in C, C++, and CUDA.
YOLO (You Only Look Once) is a state-of-the-art, real-time, object detection system that runs within the Darknet framework.
Read how Hank.ai is helping the Darknet/YOLO community: https://hank.ai/
Announcing Darknet V3 "Jazz": https://darknetcv.ai/
Please read through the Darknet/YOLO FAQ: https://darknetcv.ai/faq/
Join the Darknet/YOLO Discord server: https://discord.gg/zSq8rtW
Papers
1. Paper YOLOv7: https://arxiv.org/abs/2207.02670
2. Paper Scaled-YOLOv4: https://arxiv.org/abs/2103.05293
3. Paper YOLOv4: https://arxiv.org/abs/2004.10934
4. Paper YOLOv3: https://pjreddie.com/media/files/papers/YOLOv3.pdf
General Information
The Darknet/YOLO framework continues to be both faster and more accurate than other frameworks and versions of YOLO.
This framework is completely free and open source. You can incorporate Darknet/YOLO into existing projects and products, including commercial ones, without a license or paying a fee.
Darknet V3 ("Jazz"), released in October 2024, can accurately run the LEGO dataset videos at up to 1000 FPS when using an NVIDIA RTX 3090 GPU. This means that each video frame is read, resized, and processed by Darknet/YOLO in 1 millisecond or less.
The CPU version of Darknet/YOLO can run on simple devices such as Raspberry Pi, cloud & colab servers, desktops, laptops, and high-end training rigs. The GPU version of Darknet/YOLO requires a CUDA-capable GPU from NVIDIA.
Darknet/YOLO is known to work on Linux, Windows, and Mac. See the building instructions below.
Darknet Version
1. Version 0.x: The original Darknet tool written by Joseph Redmon in 2013-2017.
2. Version 1.x: The next popular Darknet repo maintained by Alexey Bochkovskiy between 2017-2021.
3. Version 2.x "OAK": The Darknet repo sponsored by Hank.ai and maintained by Stéphane Charette starting in 2023. It was the first one with a version command. This version brought about the following changes:
- Re-wrote the build steps for a unified CMake approach on both Windows and Linux.
- Converted the codebase to use the C++ compiler.
- Enhanced chart.png generation during training.
- Bug fixes and performance optimizations related to training time.
4. Version 2.1: The last branch of the 2.x codebase, found in the v2 branch.
5. Version 3.x "JAZZ": The next phase of development, released in October 2024.
- Removed many old and unmaintained commands.
- Implemented performance optimizations for training and inference.
- Modified the legacy C API. Applications using the original Darknet API will need minor modifications. https://darknetcv.ai/api/api.html
- Introduced a new Darknet V3 C and C++ API: https://darknetcv.ai/api/api.html
- Added new apps and sample code in src-examples: https://darknetcv.ai/api/files.html
You can always checkout the previous v2 branch if you need to run one of the commands from that version. Let us know if you encounter any missing commands so we can investigate adding them back.
MSCOCO Pre-trained Weights
Several popular versions of YOLO were pre-trained for convenience on the MSCOCO dataset. This dataset has 80 classes, which can be seen in the text file cfg/coco.names.
There are several other simpler datasets and pre-trained weights available for testing Darknet/YOLO, such as LEGO Gears and Rolodex. See the Darknet/YOLO FAQ for details.
The MSCOCO pre-trained weights can be downloaded from several different locations, including this repository:
YOLOv2 (November 2016):
yolov2-tiny.weights
yolov2-full.weights
YOLOv3 (May 2018):
yolov3-tiny.weights
yolov3-full.weights
YOLOv4 (May 2020):
yolov4-tiny.weights
yolov4-full.weights
YOLOv7 (August 2022):
yolov7-tiny.weights
yolov7-full.weights
The MSCOCO pre-trained weights are provided for demo purposes only. The corresponding .cfg and .names files for MSCOCO are in the cfg directory. Example commands:
`bash
wget --no-clobber https://github.com/hank-ai/darknet/releases/download/v2.0/yolov4-tiny.weights
darknet02displayannotatedimages coco.names yolov4-tiny.cfg yolov4-tiny.weights image1.jpg
darknet03display_videos coco.names yolov4-tiny.cfg yolov4-tiny.weights video1.avi
DarkHelp coco.names yolov4-tiny.cfg yolov4-tiny.weights image1.jpg
DarkHelp coco.names yolov4-tiny.cfg yolov4-tiny.weights video1.avi
`
Note that you are encouraged to train your own networks. MSCOCO is primarily used to confirm that everything is working correctly.
Building
The various build methods available in the past (pre-2023) have been merged into a single unified solution. Darknet requires C++17 or newer, OpenCV, and uses CMake to generate the necessary project files.
You do not need to know C++ to build, install, or run Darknet/YOLO, just like you don't need to be a mechanic to drive a car.
Google Colab
The Google Colab instructions are the same as the Linux instructions. Several Jupyter notebooks are available showing how to perform various tasks, such as training a new network.
See the notebooks in the colab subdirectory, or follow the Linux instructions below.
Linux CMake Method
Darknet build tutorial for Linux
1. Optional: If you have a modern NVIDIA GPU, you can install either CUDA or CUDA+cuDNN at this point. If installed, Darknet will use your GPU to speed up image (and video) processing.
2. Install Necessary Packages:
`bash
sudo apt-get install build-essential git libopencv-dev cmake
`
3. Clone the Darknet Repository:
`bash
mkdir ~/srccd ~/src
git clone https://github.com/hank-ai/darknet
`
4. Create Build Directory:
`bash
cd darknet
mkdir build
cd build
`
5. Generate CMake Project Files:
`bash
cmake -DCMAKEBUILDTYPE=Release ..
`
Important: You must delete the CMakeCache.txt file from your Darknet build directory to force CMake to re-find all of the necessary files.
6. Build Darknet:
`bash
make -j4 package
`
7. Install Darknet Package:
`bash
sudo dpkg -i darknet-VERSION.deb
`
Installing CUDA and cuDNN (Optional)
Darknet can run without CUDA, but if you want to train a custom network, either CUDA or CUDA+cuDNN is required.
1. Install CUDA:
- Visit https://developer.nvidia.com/cuda-downloads to download and install CUDA.
- Make sure you can run nvcc and nvidia-smi. You may need to modify your PATH variable.
2. Install cuDNN:
- Visit https://developer.nvidia.com/rdp/cudnn-download or https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html#cudnn-package-manager-installation-overview to download and install cuDNN.
Upgrading CUDA or cuDNN
If you install CUDA or CUDA+cuDNN at a later time, or upgrade to a newer version of the NVIDIA software:
1. Re-build Darknet:
- Delete the CMakeCache.txt file from your Darknet build directory.
- Run the cmake and make commands again.
Advanced Users
To build an RPM installation file instead of a DEB file, edit the relevant lines in CM_package.cmake before running make -j4 package.
`cmake
# SET (CPACK_GENERATOR "DEB")
SET (CPACK_GENERATOR "RPM")
`
To install the installation package once it has finished building, use the usual package manager for your distribution. For example, on Debian-based systems such as Ubuntu:
`bash
sudo dpkg -i darknet-2.0.1-Linux.deb
`
Testing the Installation
After installation, you should have the following files:
/usr/bin/darknet: The Darknet executable. Run darknet version from the CLI to confirm it is installed correctly.
/usr/include/darknet.h: The Darknet API for C, C++, and Python developers.
/usr/include/darknet_version.h: Contains version information for developers.
/usr/lib/libdarknet.so: The library to link against for C, C++, and Python developers.
/opt/darknet/cfg/...: Where all the .cfg templates are stored.
Run the following command to test the installation:
`bash
darknet version
`
Windows CMake Method
Darknet build tutorial for Windows
1. Install Required Software:
- Open a normal cmd.exe command prompt window and run the following commands:
`bash
winget install Git.Git
winget install Kitware.CMake
winget install nsis.nsis
winget install Microsoft.VisualStudio.2022.Community
`
2. Modify Visual Studio Installation:
- Click on the "Windows Start" menu and run "Visual Studio Installer."
- Click on "Modify."
- Select "Desktop Development With C++."
- Click on "Modify" in the bottom-right corner, then click on "Yes."
3. Install Microsoft VCPKG:
- Once everything is downloaded and installed, click on the "Windows Start" menu again and select "Developer Command Prompt for VS 2022." Do not use PowerShell for these steps!
- Run the following commands:
`bash
cd c:
mkdir c:src
cd c:src
git clone https://github.com/microsoft/vcpkg
cd vcpkg
bootstrap-vcpkg.bat
.vcpkg.exe integrate install
.vcpkg.exe integrate powershell
.vcpkg.exe install opencv[contrib,dnn,freetype,jpeg,openmp,png,webp,world]:x64-windows
`
Important: Be patient at this last step as it can take a long time to run. It needs to download and build many things.
4. Optional: Install CUDA and cuDNN
- If you have a modern NVIDIA GPU, you can install either CUDA or CUDA+cuDNN at this point. If installed, Darknet will use your GPU to speed up image (and video) processing.
- You must delete the CMakeCache.txt file from your Darknet build directory to force CMake to re-find all of the necessary files.
- Remember to re-build Darknet.
5. Install CUDA:
- Visit https://developer.nvidia.com/cuda-downloads to download and install CUDA.
- Make sure you can run nvcc.exe and nvidia-smi.exe. You may need to modify your PATH variable.
6. Install cuDNN:
- Visit https://developer.nvidia.com/rdp/cudnn-download or https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html#download-windows to download and install cuDNN.
- Once you download cuDNN, unzip and copy the bin, include, and lib directories into C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/[version]/. You may need to overwrite some files.
7. Clone the Darknet Repository and Build:
`bash
cd c:src
git clone https://github.com/hank-ai/darknet.git
cd darknet
mkdir build
cd build
cmake -DCMAKEBUILDTYPE=Release -DCMAKETOOLCHAINFILE=C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake ..
msbuild.exe /property:Platform=x64;Configuration=Release /target:Build -maxCpuCount -verbosity:normal -detailedSummary darknet.sln
msbuild.exe /property:Platform=x64;Configuration=Release PACKAGE.vcxproj
`
8. Copy CUDA DLLs (Optional):
- If you get an error about some missing CUDA or cuDNN DLLs, such as cublas64_12.dll, manually copy the CUDA .dll files into the same output directory as darknet.exe. For example:
`bash
copy "C:Program FilesNVIDIA GPU Computing ToolkitCUDAv12.2bin*.dll" src-cliRelease
`
9. Re-run msbuild.exe to Generate the NSIS Installation Package:
`bash
msbuild.exe /property:Platform=x64;Configuration=Release PACKAGE.vcxproj
`
Advanced Users
Instead of running the Developer Command Prompt, you can use a normal command prompt or ssh into the device and manually run Program FilesMicrosoft Visual Studio2022CommunityCommon7ToolsVsDevCmd.bat.
You can add many other optional modules when building OpenCV. Run .vcpkg.exe search opencv to see the full list.
The output of the cmake command is a normal Visual Studio solution file, Darknet.sln. You can ignore the command-line and load the Darknet project in Visual Studio if you are a software developer who regularly uses the Visual Studio GUI.
Testing the Installation
You should now have the following file: C:srcDarknetbuildsrc-cliReleasedarknet.exe. Run the following command to test the installation:
`bash
C:srcDarknetbuildsrc-cliReleasedarknet.exe version
`
To correctly install Darknet, the libraries, the include files, and the necessary DLLs, run the NSIS installation wizard that was built in the last step. See the file darknet-VERSION.exe in the build directory. For example:
`bash
darknet-2.0.31-win64.exe
`
Installing the NSIS installation package will:
Create a directory called Darknet, such as C:Program FilesDarknet.
Install the CLI application, darknet.exe, and other sample apps.
Install the required 3rd-party .dll files, such as those from OpenCV.
Install the necessary Darknet .dll, .lib, and .h files to use darknet.dll from another application.
Install the template .cfg files.
Run the following command to test the installation after running the NSIS wizard:
`bash
C:Program FilesDarknetbindarknet.exe version
`
Using Darknet
CLI
The following is not a complete list of all commands supported by Darknet.
In addition to the Darknet CLI, note the DarkHelp project CLI, which provides an alternative CLI to Darknet/YOLO. The DarkHelp CLI also has several advanced features that are not available directly in Darknet. You can use both the Darknet CLI and the DarkHelp CLI together; they are not mutually exclusive.
For most of the commands shown below, you'll need the .weights file with the corresponding .names and .cfg files. You can either train your own network (highly recommended!) or download a neural network that someone has already trained and made available for free on the internet. Examples of pre-trained datasets include:
LEGO Gears (finding objects in an image)
Rolodex (finding text in an image)
MSCOCO (standard 80-class object detection)
Commands to Run
1. Get Help:
`bash
darknet help
`
2. Check Version:
`bash
darknet version
`
3. Predict Using an Image:
- V2:
`bash
darknet detector test cars.data cars.cfg cars_best.weights image1.jpg
`
- V3:
`bash
darknet02displayannotatedimages cars.cfg image1.jpg
`
- DarkHelp:
`bash
DarkHelp cars.cfg cars.cfg cars_best.weights image1.jpg
`
4. Output Coordinates:
- V2:
`bash
darknet detector test animals.data animals.cfg animalsbest.weights -extoutput dog.jpg
`
- V3:
`bash
darknet01inference_images animals dog.jpg
`
- DarkHelp:
`bash
DarkHelp --json animals.cfg animals.names animals_best.weights dog.jpg
`
5. Working with Videos:
- V2:
`bash
darknet detector demo animals.data animals.cfg animalsbest.weights -extoutput test.mp4
`
- V3:
`bash
darknet03display_videos animals.cfg test.mp4
`
- DarkHelp:
`bash
DarkHelp animals.cfg animals.names animals_best.weights test.mp4
`
6. Reading from a Webcam:
- V2:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -c 0
`
- V3:
`bash
darknet08display_webcam animals
`
7. Save Results to a Video:
- V2:
`bash
darknet detector demo animals.data animals.cfg animalsbest.weights test.mp4 -outfilename res.avi
`
- V3:
`bash
darknet05processvideosmultithreaded animals.cfg animals.names animals_best.weights test.mp4
`
- DarkHelp:
`bash
DarkHelp animals.cfg animals.names animals_best.weights test.mp4
`
8. JSON Output:
- V2:
`bash
darknet detector demo animals.data animals.cfg animalsbest.weights test50.mp4 -jsonport 8070 -mjpegport 8090 -extoutput
`
- V3:
`bash
darknet06imagestojson animals image1.jpg
`
- DarkHelp:
`bash
DarkHelp --json animals.names animals.cfg animals_best.weights image1.jpg
`
9. Running on a Specific GPU:
- V2:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -i 1 test.mp4
`
10. Checking Accuracy of the Neural Network:
`bash
darknet detector map driving.data driving.cfg driving_best.weights ...
`
Output:
`
Id Name AvgPrecision TP FN FP TN Accuracy ErrorRate Precision Recall Specificity FalsePosRate
-- ---- ------------ ------ ------ ------ ------ -------- --------- --------- ------ ----------- ------------
0 vehicle 91.2495 32648 3903 5826 65129 0.9095 0.0905 0.8486 0.8932 0.9179 0.0821
1 motorcycle 80.4499 2936 513 569 5393 0.8850 0.1150 0.8377 0.8513 0.9046 0.0954
2 bicycle 89.0912 570 124 104 3548 0.9475 0.0525 0.8457 0.8213 0.9715 0.0285
3 person 76.7937 7072 1727 2574 27523 0.8894 0.1106 0.7332 0.8037 0.9145 0.0855
4 many vehicles 64.3089 1068 509 733 11288 0.9087 0.0913 0.5930 0.6772 0.9390 0.0610
5 green light 86.8118 1969 239 510 4116 0.8904 0.1096 0.7943 0.8918 0.8898 0.1102
6 yellow light 82.0390 126 38 30 1239 0.9525 0.0475 0.8077 0.7683 0.9764 0.0236
7 red light 94.1033 3449 217 451 4643 0.9237 0.0763 0.8844 0.9408 0.9115 0.0885
`
11. Checking Accuracy mAP@IoU=75:
`bash
darknet detector map animals.data animals.cfg animalsbest.weights -iouthresh 0.75
`
12. Recalculating Anchors:
- DarkMark: It's best to recalculate anchors in DarkMark, as it runs 100 consecutive times and selects the best anchors from all the ones calculated.
- Darknet: If you want to use the old method in Darknet:
`bash
darknet detector calcanchors animals.data -numof_clusters 6 -width 320 -height 256
`
13. Train a New Network:
`bash
cd ~/nn/animals/
darknet detector -map -dont_show train animals.data animals.cfg
`
Training
Quick Links to Relevant Sections of the Darknet/YOLO FAQ
1. How should I setup my files and directories?
2. Which configuration file should I use?
3. What command should I use when training my own network?
Using DarkMark for Annotation and Training (Recommended)
The simplest way to annotate and train is with DarkMark, which creates all the necessary Darknet files. This is highly recommended for training a new neural network.
Manually Setting Up Files to Train a Custom Network
If you prefer manual setup, follow these steps:
1. Create a New Folder:
- Create a new folder to store your training files. For example, you could create ~/nn/animals/ to train a network for animal detection.
2. Copy a Configuration File Template:
- Copy one of the Darknet configuration files from cfg/ as a template. For instance, you could use cfg/yolov4-tiny.cfg. Place this in the folder you created. Now you should have ~/nn/animals/animals.cfg.
3. Create a animals.names File:
- Create a text file called animals.names in the same folder as the configuration file.
4. Edit the animals.names File:
- List the classes you want to detect, one entry per line, with no blank lines or comments. For example:
`
dog
cat
bird
horse
`
5. Create a animals.data File:
- Create a text file called animals.data in the same folder.
- For example, the animals.data file could contain:
`
classes=4
train=/home/username/nn/animals/animals_train.txt
valid=/home/username/nn/animals/animals_valid.txt
names=/home/username/nn/animals/animals.names
backup=/home/username/nn/animals
`
6. Create a Dataset Folder:
- Create a folder to store your images and annotations. For example, you could create ~/nn/animals/dataset.
7. Annotate Images:
- Each image needs a corresponding .txt file with annotations. The format of these .txt files is specific and requires the exact coordinates for the annotations. Use DarkMark or similar software to annotate your images.
8. Create animalstrain.txt and animalsvalid.txt:
- These text files list the images used for training and validation, respectively. Each image should be on a separate line, with relative or absolute paths.
9. Modify the Configuration File:
- Open animals.cfg with a text editor and make the following modifications:
- batch=64: Ensure this value is set.
- subdivisions: The best value to use is 1. You may need to increase this value depending on your GPU memory and network dimensions.
- maxbatches: Set this to a reasonable value, typically 2000 times the number of classes. For this example, use maxbatches=8000 (4 classes * 2000).
- steps: Set these to 80% and 90% of maxbatches. For this example, use steps=6400,7200 (since maxbatches=8000).
- width and height: Set these to your desired network dimensions. See the Darknet/YOLO FAQ for guidance on choosing the best size.
- classes: Search for all instances of this line and modify it to match the number of classes in your .names file (in this example, classes=4).
- filters: Search for all instances of this line in the [convolutional] sections before each [yolo] section. The value to use is (numberofclasses + 5) 3. For this example, use filters=27 (4 + 5 3).
10. Start Training:
`bash
cd ~/nn/animals/
darknet detector -map -dont_show train animals.data animals.cfg
`
11. Monitoring Training Progress:
- Be patient! The best weights will be saved as animals_best.weights.
- You can monitor the progress of training by viewing the chart.png file.
- See the Darknet/YOLO FAQ for additional parameters that you might want to use during training.
12. Adding Verbosity to Training Output:
`bash
darknet detector -map -dont_show --verbose train animals.data animals.cfg
`
Other Tools and Links
DarkMark: For managing Darknet/YOLO projects, annotating images, verifying annotations, and generating files for Darknet training.
DarkHelp: For a robust alternative CLI to Darknet, using image tiling, object tracking in videos, and a robust C++ API that can be used in commercial applications.
Darknet/YOLO FAQ: https://darknetcv.ai/faq/
Stéphane's YouTube Channel: https://www.youtube.com/channel/UCYQ2k0L3X0c56l9gE2r1RQ
Darknet/YOLO Discord Server: https://discord.gg/zSq8rtW
Roadmap
Last updated 2024-10-30:
Completed
Swapped out qsort() for std::sort() where used during training (some obscure ones remain).
Removed check_mistakes, getchar(), and system().
Converted Darknet to use the C++ compiler (g++ on Linux, VisualStudio on Windows).
Fixed Windows build.
Fixed Python support.
Built Darknet library.
Re-enabled labels on predictions ("alphabet" code).
Re-enabled CUDA/GPU code.
Re-enabled CUDNN.
Re-enabled CUDNN half.
Do not hard-code the CUDA architecture.
Improved CUDA version information.
Re-enabled AVX.
Removed old solutions and Makefile.
Made OpenCV non-optional.
Removed dependency on the old pthread library.
Removed STB.
Re-wrote CMakeLists.txt to use the new CUDA detection.
Removed old "alphabet" code, and deleted the 700+ images in data/labels.
Built out-of-source.
Improved version number output.
Performance optimizations related to training (on-going task).
Performance optimizations related to inference (on-going task).
Used pass-by-reference where possible.
Cleaned up .hpp files.
Re-wrote darknet.h.
Do not cast cv::Mat to void* but use it as a proper C++ object.
Fixed or made consistent how internal image structure gets used.
Fixed build for ARM-based Jetson devices.
- Original Jetson devices are unlikely to be fixed since they are no longer supported by NVIDIA (no C++17 compiler).
- New Jetson Orin devices are working.
Fixed Python API in V3.
Improved support for Python. (Any Python developers want to help with this?)
Short-term Goals
Swap out printf() for std::cout (in progress).
Look into old ZED camera support.
Improve and make consistent command line parsing (in progress).
Mid-term Goals
Remove all char* code and replace with std::string.
Do not hide warnings and clean up compiler warnings (in progress).
Improve the use of cv::Mat instead of the custom image structure in C (in progress).
Replace old list functionality with std::vector or std::list.
Fix support for 1-channel greyscale images.
Add support for N-channel images where N > 3 (e.g., images with an additional depth or thermal channel).
On-going code cleanup (in progress).
Long-term Goals
Fix CUDA/CUDNN issues with all GPUs.
Re-write CUDA+cuDNN code.
Look into adding support for non-NVIDIA GPUs.
Rotated bounding boxes, or some sort of "angle" support.
Keypoints/skeletons.
Heatmaps (in progress).
Segmentation.
