2026 Ultimate labelImg Tutorial: Pascal VOC/YOLO Annotation + Efficiency Optimization Tips

labelImg is an essential graphical image annotation tool for computer vision (CV) tasks, widely used for object detection model training. This guide details labelImg's installation, cross-platform deployment, Pascal VOC/YOLO format switching, shortcut operations, batch annotation workflows, and troubleshooting solutions. Optimized for English-speaking users, it includes efficiency-boosting tips and enterprise-level customization support, helping both beginners and professionals streamline annotation workflows and improve data quality.

Preface

In computer vision projects, high-quality data annotation is the cornerstone of accurate model training. labelImg stands out as a lightweight, open-source annotation tool with an intuitive GUI, native support for Pascal VOC and YOLO formats, and cross-platform compatibility (Windows/macOS/Linux). However, English users often face challenges like unclear documentation, shortcut confusion, and format conversion issues.

This guide, based on labelImg v2.0.0 (the latest stable version), provides a step-by-step English-friendly tutorial—from installation to advanced techniques. It addresses common pain points such as dependency conflicts, annotation inefficiency, and cross-format compatibility, making it suitable for CV practitioners, students, and researchers worldwide.

I. Quick Start

1.1 Installation & Launch

labelImg offers two deployment options: precompiled executables (for non-technical users) and source code execution (for developers/customization).

Windows Users (Recommended)

1. Download labelImg-2.0.0.exe from the official Gitee release page

2. Double-click to run (no Python or additional dependencies required)

3. (Optional) Create a desktop shortcut for quick access

macOS Users

1. Download the labelImg-2.0.0.dmg disk image

2. Open the dmg file and drag labelImg.app to the Applications folder

3. For first launch: Right-click → "Open" (to bypass macOS security warnings)

Linux Users

# Install system dependencies
sudo apt-get install python3-pyqt5 pyqt5-dev-tools
pip3 install lxml
​
# Clone repository
git clone https://github.com/tekintian/labelImg.git
cd labelImg
​
# Compile resource files
pyrcc5 -o resources.py resources.qrc
​
# Launch the application
python3 labelImg.py

Source Code Execution (Cross-Platform)

# Clone repository (GitHub for global access)
git clone https://github.com/tekintian/labelImg.git
cd labelImg
​
# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
​
# Install dependencies
pip install -r requirements.txt
​
# Compile Qt resource files (critical step)
pyrcc5 -o resources.py resources.qrc
​
# Run labelImg
python labelImg.py

1.2 Interface Overview

labelImg features a minimalist, user-friendly interface with clear sections:

💡 Tip: First-time users should check "Help" → "Shortcut Keys"—mastering shortcuts can boost annotation efficiency by 50%+.

II. Basic Operations

2.1 Image Loading

Single Image Loading

File → Open (Ctrl+O)

Supported formats: JPG, PNG, BMP, TIFF, etc. Use English file paths to avoid loading errors.

Batch Image Loading (Recommended)

File → Open Directory (Ctrl+R)

After selecting a folder:

• Press D to navigate to the next image

• Press A to navigate to the previous image

• The status bar shows "Current/Total" count (e.g., 1/100)

💡 Best Practice: Organize images in dataset/images—annotation files will be auto-saved to the same directory (or custom dataset/annotations).

2.2 Creating Annotation Boxes

Standard Workflow

1. Enter drawing mode: Press W or click the "Create Rectangle Box" button in the toolbar

2. Draw a box: Click and drag the mouse to enclose the target object

3. Enter label: Type the class name (e.g., person, car) in the pop-up input box

4. Confirm: Press Enter or click "OK" to finalize the annotation

Useful Tips

• Hold Shift while dragging to draw a square box

• Press Esc to cancel the current drawing

• Press Tab for label auto-suggestions (requires predefined labels—see Section 3.2)

2.3 Editing Annotations

Resizing/Moving Boxes

• Select a box: Click anywhere on the annotation to reveal 8 resizing handles

• Resize: Drag the corner/edge handles to adjust dimensions

• Move: Drag the center of the box to reposition it

Modifying Labels

Method 1: Double-click the annotation box → Edit label text directly Method 2: Double-click the entry in the left panel → Update label Method 3: Right-click the box → Select "Edit Label"

Deleting Annotations

• Single box: Select and press Delete (or right-click → "Delete")

• Clear all: Edit → Delete All Annotations (Ctrl+Delete)

2.4 Saving Annotations

Manual Save

File → Save (Ctrl+S)

• Pascal VOC format: Generates a .xml file with the same name as the image

• YOLO format: Generates a .txt file with the same name as the image

Save As

File → Save As (Ctrl+Shift+S)

Customize the save path (ideal for separating images and annotations).

Auto-Save (Recommended)

View → Auto-Save

Features:

• Automatically saves annotations when navigating between images (A/D)

• Prevents data loss from forgotten manual saves

• Essential for batch annotation workflows

III. Advanced Features

3.1 Annotation Format Switching

labelImg natively supports two industry-standard formats, switchable at any time:

Pascal VOC XML Format (Default)

File → Switch Save Format → PascalVOC

Use Case: TensorFlow/PyTorch frameworks, VOC competition datasets File Structure:

<annotation>
  <folder>images</folder>
  <filename>img001.jpg</filename>
  <size>
    <width>1920</width>
    <height>1080</height>
    <depth>3</depth>
  </size>
  <object>
    <name>person</name>  <!-- Label name -->
    <difficult>0</difficult>  <!-- Difficulty flag -->
    <bndbox>
      <xmin>100</xmin>  <!-- Top-left X coordinate -->
      <ymin>200</ymin>  <!-- Top-left Y coordinate -->
      <xmax>300</xmax>  <!-- Bottom-right X coordinate -->
      <ymax>400</ymax>  <!-- Bottom-right Y coordinate -->
    </bndbox>
  </object>
</annotation>

YOLO Format

File → Switch Save Format → YOLO

Use Case: YOLOv3/v4/v5/v8 series models Format Specification:

# Structure: Class ID → X center → Y center → Width → Height (normalized to 0-1)
0 0.5 0.5 0.4 0.3  # Class: person, Center (0.5,0.5), Width: 0.4, Height: 0.3

⚠️ Critical Notes:

1. YOLO format requires data/predefined_classes.txt (class IDs follow line order)

2. Coordinates are automatically normalized to [0, 1]

3. Annotation files must share the same name as images and reside in the same directory

3.2 Predefined Labels (Efficiency Booster)

Predefine frequently used labels to eliminate repetitive typing:

Setup Steps

1. Open labelImg/data/predefined_classes.txt

2. Add one label per line (sorted by frequency of use):

   person
   car
   bicycle
   dog
   cat
   bus
   truck

3. Save the file and restart labelImg

4. A dropdown menu will appear when creating new annotations for quick selection

💡 Pro Tip: Create project-specific label files (e.g., classes_traffic.txt, classes_face.txt) and replace predefined_classes.txt as needed.

3.3 Default Label Function

Ideal for single-class annotation tasks (e.g., only annotating person):

1. Check "Use Default Label" at the bottom of the left panel

2. Enter the default label (e.g., person)

3. All new annotations will automatically use this label

3.4 Difficulty Marking

Mark ambiguous, occluded, or hard-to-identify objects (stored in the <difficult> field for Pascal VOC):

Operation

1. Select an annotation box

2. Right-click → "Mark as Difficult" (or press Ctrl+D)

3. The box will change to a dashed line to indicate it’s a difficult sample

📌 Use Case: Exclude difficult samples during model training or process them separately.

3.5 Annotation Verification

Quickly check for missing annotations in datasets:

1. Click the "Verify" button in the toolbar (or press Ctrl+V)

2. The tool automatically detects annotations:

   • Annotated images: Status bar shows "Verified"

   • Unannotated images: Status bar shows a red warning "No Annotations"

3. Batch verification: Use D to scan all images after opening a directory

3.6 Undo/Redo

Recover from annotation mistakes without manual deletion:

• Undo: Ctrl+Z (reverse the last operation)

• Redo: Ctrl+Y / Ctrl+Shift+Z (restore undone operations)

IV. Shortcut Cheat Sheet

Core Operations (Must-Know)

File Operations

View Controls

Editing Operations

V. View & Customization

5.1 Canvas Zoom & Pan

• Precision zoom: Use Ctrl++/Ctrl+- or toolbar buttons

• Quick fit:

  • Ctrl+0: Auto-adjust image to fit window (recommended)

  • Ctrl+1: Fit width while maintaining aspect ratio

• Pan: Hold right-click and drag (when image is zoomed in)

5.2 Annotation Box Customization

Color Settings

View → Box Color

New annotations will use the selected color (existing annotations remain unchanged)—useful for distinguishing classes or annotation stages.

Display Options

View → Display Options

Configurable settings:

• ✅ Show label text (enabled by default)

• ✅ Show annotation IDs (for counting)

• ✅ Show crosshair (for precise positioning)

• ✅ Show bounding boxes (core function, cannot be disabled)

5.3 Language Support

labelImg includes three built-in languages. To switch:

1. Language → English / 简体中文 (Simplified Chinese) / 繁体中文 (Traditional Chinese)

2. Restart the application for changes to take effect

Adding Custom Languages (Advanced)

1. Create a strings-xx-XX.properties file in resources/strings/ (e.g., strings-ja.properties for Japanese)

2. Copy and translate content from strings.properties

3. Add the new file path to resources.qrc

4. Recompile resources: pyrcc5 -o resources.py resources.qrc

VI. Workflow Best Practices

6.1 Standard Annotation Workflow

Step 1: Data Preparation

dataset/
├── images/          # Raw images (unified as JPG/PNG)
│   ├── 001.jpg
│   ├── 002.jpg
│   └── ...
├── annotations/     # Auto-generated annotation files
└── classes.txt      # YOLO class file (optional)

Step 2: Tool Configuration

1. Edit predefined_classes.txt to add project-specific labels

2. Select annotation format (Pascal VOC/YOLO)

3. Enable "Auto-Save"

4. Set default label (for single-class tasks)

Step 3: Efficient Annotation

Open Directory → Press W to draw box → Press Enter to confirm → Press D for next image

Step 4: Quality Control

1. Use the "Verify" function to scan for unannotated images

2. Randomly sample images to check annotation accuracy (bounding box alignment)

3. Analyze label distribution to ensure dataset balance

6.2 Team Collaboration

Task Division

• By image number: e.g., Team A handles 001-500, Team B handles 501-1000

• By class: e.g., Team A annotates "person", Team B annotates "car" (for multi-class tasks)

Standardization

1. Share predefined_classes.txt to ensure consistent label naming

2. Establish annotation guidelines (e.g., boxes must fully enclose objects)

3. Use version control (Git) to manage annotation files and avoid overwrites

Quality Assurance

• Cross-validation: Randomly check 10% of each team’s annotations

• Create an annotation guideline document for edge cases (e.g., occluded objects)

6.3 YOLO Format Special Guide

Required Configuration

1. Create classes.txt sorted by priority:

   person  # ID=0
   car     # ID=1
   bike    # ID=2

2. Replace predefined_classes.txt with classes.txt in the data directory

3. Switch to YOLO save format

Format Validation Script

import os
​
def check_yolo_format(txt_path, img_width, img_height):
    """Validate YOLO annotation format"""
    with open(txt_path, 'r') as f:
        lines = f.readlines()
    
    for line in lines:
        parts = line.strip().split()
        # Check field count
        if len(parts) != 5:
            return False, f"Invalid field count: {line}"
        # Check coordinate range (0-1)
        try:
            class_id = int(parts[0])
            x, y, w, h = map(float, parts[1:])
            if not (0 <= x <= 1 and 0 <= y <= 1 and 0 <= w <= 1 and 0 <= h <= 1):
                return False, f"Coordinates out of range: {line}"
        except ValueError:
            return False, f"Format error: {line}"
    return True, "Format valid"
​
# Usage example
# check_yolo_format("annotations/001.txt", 1920, 1080)

VII. Troubleshooting

7.1 Launch Issues

7.2 Functionality Issues

7.3 Performance Issues

VIII. Advanced Tips & Efficiency Hacks

8.1 Annotation Efficiency Boosters

1. Prioritize labels: Place frequently used labels in the first 3 lines of predefined list

2. Reuse annotations: Copy (Ctrl+C) and paste (Ctrl+V) boxes for similar objects across images

3. Batch renaming: Standardize image names (e.g., 0001.jpg, 0002.jpg) with scripts for easier management

4. Semi-automated annotation: Use simple scripts to generate candidate boxes (e.g., based on color/contour detection) for manual refinement

8.2 Annotation Data Analysis

Pascal VOC Label Distribution

import os
import xml.etree.ElementTree as ET
​
def count_voc_labels(anno_dir):
    """Count label distribution in Pascal VOC annotations"""
    label_count = {}
    for xml_file in os.listdir(anno_dir):
        if not xml_file.endswith('.xml'):
            continue
        tree = ET.parse(os.path.join(anno_dir, xml_file))
        root = tree.getroot()
        for obj in root.findall('object'):
            label = obj.find('name').text
            label_count[label] = label_count.get(label, 0) + 1
    
    print("=== Annotation Label Statistics ===")
    for label, count in sorted(label_count.items()):
        print(f"{label}: {count}")
    print(f"Total annotations: {sum(label_count.values())}")
​
# Usage: Analyze annotations in the 'annotations' directory
count_voc_labels("dataset/annotations")

YOLO Label Distribution

def count_yolo_labels(txt_dir, classes_file):
    """Count label distribution in YOLO annotations"""
    # Load class mapping
    with open(classes_file, 'r') as f:
        classes = [line.strip() for line in f.readlines()]
    
    label_count = {cls:0 for cls in classes}
    for txt_file in os.listdir(txt_dir):
        if not txt_file.endswith('.txt'):
            continue
        with open(os.path.join(txt_dir, txt_file), 'r') as f:
            lines = f.readlines()
        for line in lines:
            class_id = int(line.strip().split()[0])
            label = classes[class_id]
            label_count[label] += 1
    
    print("=== YOLO Annotation Statistics ===")
    for label, count in label_count.items():
        print(f"{label}: {count}")
​
# Usage example
# count_yolo_labels("dataset/annotations", "data/classes.txt")

8.3 Custom Development (For Developers)

Adding New Annotation Formats (e.g., COCO)

1. Implement read/write classes for COCO format, referencing libs/pascal_voc_io.py/libs/yolo_io.py

2. Add format switching menu in labelImg.py

3. Compile and test to ensure correct annotation generation

Batch Processing Script

import os
import shutil
​
def batch_convert_format(input_dir, output_dir, from_format="voc", to_format="yolo"):
    """Batch convert annotation formats (implement core logic as needed)"""
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)
    
    for file in os.listdir(input_dir):
        if from_format == "voc" and file.endswith('.xml'):
            # Convert XML to YOLO TXT
            basename = os.path.splitext(file)[0]
            # Core conversion logic...
            # Save to output_dir/{basename}.txt

IX. Enterprise-Grade Customization Services

While labelImg meets most basic annotation needs, enterprise users often require tailored solutions:

• Custom annotation formats (e.g., proprietary JSON structures)

• AI-assisted annotation (auto-generate candidate boxes with pre-trained models)

• Integration with internal data management systems (auto-upload annotations)

• Custom UI and workflows (adapt to team collaboration processes)

• Batch annotation automation scripts

We specialize in custom internet software development with a team of engineers averaging 10+ years of experience. Proficient in Python, Go, Java, and CV technologies, we’ve delivered tailored solutions for 20+ industries with a 98%+ technical adaptation rate. Whether you need labelImg customization or end-to-end enterprise informatization, we provide full-cycle services from requirement analysis to deployment and maintenance.

👉 Get in Touch:

• Official Website: https://dev.tekin.cn

• Business QQ: 932256355

• Service Commitment: 24/7 technical support, 1-on-1 dedicated service, 90%+ 5-year client retention rate

X. Conclusion

labelImg’s lightweight design, ease of use, and cross-platform compatibility make it the top choice for object detection annotation. Master these key takeaways to maximize efficiency and data quality:

1. Shortcuts are game-changers: Master core shortcuts like W/D/A/Ctrl+S

2. Preconfiguration saves time: Set up predefined labels, default labels, and auto-save

3. Choose the right format: Pascal VOC for general use, YOLO for YOLO-series models

4. Quality control is critical: Verify annotations, sample checks, and distribution analysis

With this guide, you now have the skills to use labelImg from beginner to expert level. For customization or technical support, leverage our professional services or modify the open-source code to fit your needs.

References

• Official Repositories: Gitee (https://gitee.com/tekintian/labelImg), GitHub (https://github.com/tekintian/labelImg)

• Pascal VOC Specification: http://host.robots.ox.ac.uk/pascal/VOC/

• YOLO Format Documentation: https://docs.ultralytics.com/datasets/detect/

• PyQt5 Developer Guide: https://www.riverbankcomputing.com/static/Docs/PyQt5/

• Customization Services: https://dev.tekin.cn (QQ: 932256355)