How to Run YOLOv8 Real-Time Object Detection on Webcam

Table of Contents

• How to Run YOLOv8 Real-Time Object Detection on Webcam
  • Why YOLOv8 for Real-Time Webcam Detection
  • Prerequisites and Environment Setup
• Create and activate virtual environment
• Upgrade pip and install core dependencies
  • Building the Real-Time Detection Pipeline
    • Video Capture with Threading
    • YOLOv8 Inference Engine
    • Display and Recording Module
  • Putting It All Together: Main Loop

📺 Watch: Neural Networks Explained

Video by 3Blue1Brown

---

Real-time object detection has become a cornerstone of modern computer vision applications, from autonomous vehicles to retail analytics and security systems. In this tutorial, you'll build a production-grade webcam object detection pipeline using Ultralytics YOLOv8, the latest iteration of the You Only Look Once family. By the end, you'll have a working system that processes live video at 30+ FPS on a consumer GPU, with proper error handling, performance monitoring, and deployment considerations.

Why YOLOv8 for Real-Time Webcam Detection

YOLOv8 represents a significant leap in the balance between speed and accuracy. According to the Ultralytics documentation, YOLOv8n (nano) achieves over 80 FPS on an NVIDIA T4 GPU while maintaining 37.3% mAP on COCO, making it ideal for real-time applications. The model's architecture improvements include a C2f module (Cross Stage Partial with 2 convolutions and feature fusion) and a decoupled head for classification and regression tasks.

For webcam-based detection, the key challenges are:

• Latency: End-to-end processing must stay under 33ms for 30 FPS
• Memory: GPU VRAM usage should not exceed 2GB for consumer hardware
• Robustness: Handling varying lighting, camera quality, and occlusions

Prerequisites and Environment Setup

Before writing any code, ensure your system meets these requirements:

Hardware:

• CPU: Intel Core i5-10400 or AMD Ryzen 5 3600 (or better)
• GPU: NVIDIA GTX 1060 6GB or better (for real-time performance)
• RAM: 16GB minimum
• Webcam: USB 2.0 or built-in (720p or 1080p)

Software:

• Python 3.10 or 3.11 (3.12 has known compatibility issues with PyTorch [4] as of June 2026)
• CUDA 11.8 or 12.1 (check with nvidia-smi)
• pip 23.0+

Create a dedicated virtual environment to avoid dependency conflicts:

# Create and activate virtual environment
python3.10 -m venv yolo_env
source yolo_env/bin/activate  # On Windows: yolo_env\Scripts\activate

# Upgrade pip and install core dependencies
pip install --upgrade pip setuptools wheel
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install ultralytics opencv-python numpy matplotlib

The ultralytics package (version 8.2.0 as of June 2026) includes YOLOv8 models, training utilities, and inference pipelines. We install PyTorch separately to ensure CUDA support—the default ultralytics installation may pull a CPU-only version.

Verify your installation:

import torch
import ultralytics

print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"Ultralytics version: {ultralytics.__version__}")

If torch.cuda.is_available() returns False, reinstall PyTorch with the correct CUDA version matching your driver.

Building the Real-Time Detection Pipeline

We'll construct a modular pipeline with three components: video capture, inference engine, and display/recording. This separation allows independent scaling and testing.

Video Capture with Threading

Standard OpenCV cv2.VideoCapture() blocks the main thread during frame reads, causing latency spikes. We'll implement a threaded capture buffer:

import cv2
import threading
import queue
import time
from dataclasses import dataclass
from typing import Optional

@dataclass
class FrameBuffer:
    """Thread-safe frame buffer with timestamp tracking."""
    frame: Optional[np.ndarray] = None
    timestamp: float = 0.0
    fps: float = 0.0

class WebcamStream:
    """Non-blocking webcam capture using a producer-consumer pattern."""

    def __init__(self, src: int = 0, width: int = 640, height: int = 480):
        self.cap = cv2.VideoCapture(src)
        if not self.cap.isOpened():
            raise RuntimeError(f"Cannot open webcam source {src}")

        # Set resolution for consistent performance
        self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, width)
        self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, height)
        self.cap.set(cv2.CAP_PROP_FPS, 30)

        # Buffer for frame exchange between threads
        self.buffer = queue.Queue(maxsize=2)
        self.stopped = False
        self.thread = threading.Thread(target=self._update, daemon=True)

    def start(self):
        """Begin background frame capture."""
        self.thread.start()
        return self

    def _update(self):
        """Continuously read frames in a separate thread."""
        while not self.stopped:
            ret, frame = self.cap.read()
            if not ret:
                self.stopped = True
                break

            # Drop old frames if buffer is full (maintains real-time)
            if self.buffer.full():
                try:
                    self.buffer.get_nowait()
                except queue.Empty:
                    pass

            self.buffer.put(frame)

    def read(self) -> Optional[np.ndarray]:
        """Get the most recent frame (non-blocking)."""
        try:
            return self.buffer.get_nowait()
        except queue.Empty:
            return None

    def stop(self):
        """Clean shutdown of capture thread."""
        self.stopped = True
        self.thread.join(timeout=1.0)
        self.cap.release()

Key design decisions:

• Queue size of 2: Prevents memory buildup while ensuring fresh frames
• Daemon thread: Automatically terminates when main process exits
• Non-blocking read: Returns None if no frame available, allowing graceful degradation

YOLOv8 Inference Engine

We'll create a reusable inference class that handles model loading, preprocessing, and postprocessing:

import numpy as np
from ultralytics import YOLO
from ultralytics.engine.results import Results
import time

class YOLODetector:
    """Production-grade YOLOv8 inference wrapper with performance tracking."""

    def __init__(self, model_path: str = "yolov8n.pt", device: str = "cuda:0"):
        self.device = device if torch.cuda.is_available() else "cpu"
        print(f"Loading model on {self.device}")

        self.model = YOLO(model_path)
        self.model.to(self.device)

        # Warm-up inference to initialize CUDA kernels
        dummy = np.zeros((640, 640, 3), dtype=np.uint8)
        self.model.predict(dummy, verbose=False)

        # Performance metrics
        self.inference_times = []
        self.fps_history = []

    def detect(self, frame: np.ndarray, conf_threshold: float = 0.5) -> Results:
        """
        Run detection on a single frame.

        Args:
            frame: BGR image from OpenCV
            conf_threshold: Minimum confidence score (0-1)

        Returns:
            Ultralytics Results object with boxes, masks, etc.
        """
        start_time = time.perf_counter()

        results = self.model.predict(
            frame,
            conf=conf_threshold,
            device=self.device,
            verbose=False,
            half=True,  # FP16 inference for 2x speedup on supported GPUs
            augment=False,  # Disable TTA for speed
        )

        inference_time = time.perf_counter() - start_time
        self.inference_times.append(inference_time)

        # Maintain rolling window of last 100 measurements
        if len(self.inference_times) > 100:
            self.inference_times.pop(0)

        return results[0]  # Single image input

    @property
    def avg_inference_time(self) -> float:
        """Averag [2]e inference time in milliseconds."""
        if not self.inference_times:
            return 0.0
        return (sum(self.inference_times) / len(self.inference_times)) * 1000

    @property
    def fps(self) -> float:
        """Estimated FPS based on inference time."""
        avg_ms = self.avg_inference_time
        return 1000 / avg_ms if avg_ms > 0 else 0.0

Critical implementation details:

• FP16 inference: The half=True parameter uses half-precision floating point, which doubles throughput on Tensor Cores (Volta+ architecture). This reduces memory bandwidth by 50% with negligible accuracy loss (typically <0.5% mAP drop).
• Warm-up pass: CUDA kernels are JIT-compiled on first inference. Running a dummy frame prevents the first real frame from having inflated latency.
• Rolling performance metrics: We track the last 100 inference times to compute stable averages without unbounded memory growth.

Display and Recording Module

For production use, we need to visualize detections and optionally record the output:

import cv2
from pathlib import Path
from datetime import datetime

class DisplayManager:
    """Handles visualization and optional video recording."""

    def __init__(self, window_name: str = "YOLOv8 Detection", 
                 record: bool = False, output_dir: str = "recordings"):
        self.window_name = window_name
        self.record = record
        self.writer = None

        if record:
            Path(output_dir).mkdir(exist_ok=True)
            self.output_path = Path(output_dir) / f"detection_{datetime.now().strftime('%Y%m%d_%H%M%S')}.mp4"

    def show(self, frame: np.ndarray, fps: float = 0.0):
        """Display frame with FPS overlay."""
        if fps > 0:
            cv2.putText(frame, f"FPS: {fps:.1f}", (10, 30),
                       cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)

        cv2.imshow(self.window_name, frame)

        if self.record and self.writer is not None:
            self.writer.write(frame)

    def start_recording(self, frame_width: int, frame_height: int, fps: int = 30):
        """Initialize video writer."""
        if self.record:
            fourcc = cv2.VideoWriter_fourcc(*'mp4v')
            self.writer = cv2.VideoWriter(
                str(self.output_path), fourcc, fps, 
                (frame_width, frame_height)
            )

    def stop_recording(self):
        """Release video writer resources."""
        if self.writer is not None:
            self.writer.release()
            self.writer = None

    def destroy(self):
        """Clean up all display resources."""
        self.stop_recording()
        cv2.destroyAllWindows()

Putting It All Together: Main Loop

Now we combine all components into a robust main loop with error handling:

import signal
import sys

def main():
    # Configuration
    MODEL_PATH = "yolov8n.pt"
    CONFIDENCE = 0.5
    RECORD = False  # Set to True to save video

    # Initialize components
    stream = WebcamStream(src=0, width=640, height=480).start()
    detector = YOLODetector(model_path=MODEL_PATH)
    display = DisplayManager(record=RECORD)

    # Graceful shutdown handler
    def signal_handler(sig, frame):
        print("\nShutting down gracefully..")
        stream.stop()
        display.destroy()
        sys.exit(0)

    signal.signal(signal.SIGINT, signal_handler)

    # Start recording if enabled
    if RECORD:
        display.start_recording(640, 480)

    print("Detection started. Press 'q' to quit, 'r' to toggle recording.")

    frame_count = 0
    fps_timer = time.perf_counter()

    while True:
        # Get frame from threaded capture
        frame = stream.read()
        if frame is None:
            time.sleep(0.001)  # Yield CPU if no frame available
            continue

        # Run detection
        results = detector.detect(frame, conf_threshold=CONFIDENCE)

        # Annotate frame with bounding boxes
        annotated_frame = results.plot()

        # Calculate and display FPS
        frame_count += 1
        if frame_count % 30 == 0:  # Update FPS every 30 frames
            elapsed = time.perf_counter() - fps_timer
            current_fps = 30 / elapsed
            fps_timer = time.perf_counter()

        display.show(annotated_frame, fps=detector.fps)

        # Handle keyboard input
        key = cv2.waitKey(1) & 0xFF
        if key == ord('q'):
            break
        elif key == ord('r'):
            RECORD = not RECORD
            if RECORD:
                display.start_recording(640, 480)
                print("Recording started")
            else:
                display.stop_recording()
                print("Recording stopped")

    # Cleanup
    stream.stop()
    display.destroy()

    # Print performance summary
    print(f"\nPerformance Summary:")
    print(f"Average inference time: {detector.avg_inference_time:.1f} ms")
    print(f"Estimated FPS: {detector.fps:.1f}")

if __name__ == "__main__":
    main()

Handling Edge Cases and Production Considerations

1. Camera Disconnection

If the webcam is unplugged during operation, cv2.VideoCapture.read() returns (False, None). Our threaded capture handles this by setting self.stopped = True. However, the main loop will continue running with None frames. Add a reconnection mechanism:

def _update(self):
    """Enhanced version with auto-reconnection."""
    while not self.stopped:
        ret, frame = self.cap.read()
        if not ret:
            print("Frame read failed, attempting reconnection..")
            self.cap.release()
            time.sleep(1)
            self.cap = cv2.VideoCapture(self.src)
            if not self.cap.isOpened():
                continue
            ret, frame = self.cap.read()
            if not ret:
                continue
        # .. rest of the method

2. GPU Memory Management

YOLOv8 models consume significant VRAM. Monitor usage with:

import pynvml  # pip install nvidia-ml-py3

def get_gpu_memory():
    pynvml.nvmlInit()
    handle = pynvml.nvmlDeviceGetHandleByIndex(0)
    info = pynvml.nvmlDeviceGetMemoryInfo(handle)
    return info.used / 1024**2  # MB

# In main loop:
if frame_count % 100 == 0:
    vram_mb = get_gpu_memory()
    if vram_mb > 1800:  # Leave headroom for other processes
        print(f"Warning: VRAM usage at {vram_mb:.0f} MB")

3. Variable Lighting Conditions

Webcam auto-exposure can cause detection flickering. Disable auto-adjustment:

# After opening the camera
self.cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 0.25)  # Disable auto exposure
self.cap.set(cv2.CAP_PROP_EXPOSURE, -4)  # Manual exposure value

4. Multi-Camera Support

For production systems with multiple cameras, use a camera manager:

class CameraManager:
    def __init__(self, camera_configs: list[dict]):
        self.streams = {}
        for config in camera_configs:
            cam_id = config['id']
            self.streams[cam_id] = WebcamStream(
                src=config['src'],
                width=config.get('width', 640),
                height=config.get('height', 480)
            ).start()

    def get_frames(self) -> dict:
        return {cam_id: stream.read() 
                for cam_id, stream in self.streams.items()}

Performance Optimization Tips

1. Model Selection: YOLOv8n (nano) runs at 80+ FPS on T4, while YOLOv8x (extra-large) achieves 15 FPS. Choose based on your accuracy needs.

2. Input Resolution: 640x640 is the default. Reducing to 320x320 doubles FPS but reduces accuracy by ~5% mAP.

3. Batch Processing: If processing multiple cameras, batch frames for GPU efficiency:

   results = model.predict(frames, batch=len(frames))
   

4. TensorRT Deployment: For maximum performance, convert to TensorRT:

   model.export(format='engine', half=True)
   trt_model = YOLO('yolov8n.engine')
   

What's Next

You now have a production-ready real-time object detection system. To extend this project:

• Add object tracking: Integrate ByteTrack or BoT-SORT for consistent object IDs across frames
• Implement alerting: Trigger webhooks or email notifications when specific objects are detected
• Deploy as a microservice: Wrap the pipeline in a FastAPI endpoint for remote access
• Explore model fine-tuning [3]: Train YOLOv8 on custom datasets using the Ultralytics training API

For further reading, check out our guides on optimizing YOLOv8 for edge devices and building multi-camera surveillance systems.

The complete code is available on GitHub. Remember to respect privacy laws when deploying camera-based systems—always obtain consent and clearly communicate monitoring policies.

---