Memory Requirements for Training PFLD: A Complete Hardware Guide

Training PFLD with default settings requires approximately 2–3 GB of GPU VRAM, but the code aggressively allocates 100% of available GPU memory via per_process_gpu_memory_fraction=1.0 in train_model.py.

The PFLD (Progressive Face Landmark Detection) repository by guoqiangqi/pfld implements a lightweight MobileNet-V2 backbone for facial landmark detection. While the model itself is compact, understanding the memory requirements for training PFLD is critical to avoid out-of-memory errors on consumer GPUs. The training script provides explicit controls for memory allocation, batch size, and input resolution that directly dictate VRAM consumption.

Default Memory Configuration in PFLD

The train_model.py script contains hardcoded defaults that determine baseline memory usage. These settings assume access to a modern NVIDIA GPU with several gigabytes of VRAM.

GPU Memory Allocation Policy

By default, PFLD configures TensorFlow to monopolize the entire GPU. At line 124 of train_model.py, the session configuration sets:

gpu_options = tf.GPUOptions(per_process_gpu_memory_fraction=1.0)

This forces TensorFlow to allocate 100% of the available GPU memory immediately upon initialization, rather than growing memory usage dynamically. On cards with limited VRAM (e.g., 4 GB or less), this aggressive allocation can trigger CUDA out-of-memory errors before training even begins.

Default Training Parameters

The argument parser in train_model.py (lines 27–29) establishes the following memory-intensive defaults:

• --image_size 112: Input tensors of shape 112 × 112 × 3 (RGB).
• --batch_size 64: Sixty-four images processed per training step.

With these defaults, the raw pixel batch alone consumes approximately 9.6 MB of memory (112 × 112 × 3 channels × 4 bytes × 64 batch size). However, the total memory footprint is significantly larger due to network activations, gradients, and optimizer states.

Estimating GPU Memory Usage for PFLD Training

A detailed breakdown of VRAM components reveals why PFLD typically requires 2–3 GB with default settings.

Model Parameters: The MobileNet-V2-style backbone defined in model2.py plus the PFLD inference head (pfld_inference) contains approximately 5–7 MB of trainable weights.

Activation Memory: During the forward pass, intermediate feature maps from depthwise separable convolutions require significant buffer space. For a batch of 64 images, activation memory typically reaches 30–40 MB.

Gradients and Optimizer States: TensorFlow maintains gradient tensors for every trainable variable (doubling the parameter memory) and additional momentum buffers if using optimizers like Adam. This adds roughly 15–20 MB.

Total Footprint: Summing these components—raw data (9.6 MB), activations (~35 MB), parameters (~6 MB), and gradients/optimizer states (~20 MB)—yields approximately 70 MB of theoretical minimum. However, TensorFlow’s memory allocator, CUDA overhead, and the per_process_gpu_memory_fraction=1.0 policy typically result in the process reserving 2–3 GB of VRAM on modern GPUs (e.g., GTX 1080 Ti or RTX 2080).

How to Reduce Memory Requirements for PFLD

If training fails with out-of-memory errors or you need to run PFLD on hardware with limited VRAM, three specific modifications to train_model.py parameters will reduce memory pressure.

Lower the Batch Size

Reducing --batch_size is the most effective method to decrease VRAM usage. The memory consumption scales roughly linearly with batch size due to activation storage.

Run training with a smaller batch size to fit on a 1–2 GB GPU:

python train_model.py \
  --file_list data/train_data/list.txt \
  --test_list data/test_data/list.txt \
  --batch_size 16 \
  --image_size 112 \
  --max_epoch 200

Reduce Input Resolution

Lowering --image_size reduces both the raw pixel buffer and the spatial dimensions of intermediate feature maps. Since convolutional memory scales with the square of resolution, changing from 112 to 96 pixels reduces activation memory by approximately 25%.

Example configuration for limited VRAM:

python train_model.py \
  --batch_size 32 \
  --image_size 96 \
  --file_list data/train_data/list.txt

Limit GPU Memory Fraction

Instead of allowing TensorFlow to monopolize the entire GPU, modify line 124 in train_model.py to cap the allocation. This prevents the process from attempting to reserve more VRAM than available, which is essential for shared GPU environments or cards with less than 4 GB.

Edit train_model.py:

# Original configuration (line 124)

# gpu_options = tf.GPUOptions(per_process_gpu_memory_fraction=1.0)

# Modified for 50% allocation

gpu_options = tf.GPUOptions(per_process_gpu_memory_fraction=0.5)

Alternatively, allow growth instead of pre-allocation by adding:

gpu_options = tf.GPUOptions(allow_growth=True)

Key Source Files Controlling Memory Usage

Understanding the repository structure helps diagnose memory issues. The following files in guoqiangqi/pfld directly influence VRAM consumption:

• train_model.py: Contains the tf.GPUOptions configuration (line 124) and argument parsers for batch_size and image_size (lines 27–29).
• model2.py: Defines the mobilenet_v2 backbone and pfld_inference head; determines the parameter count and activation topology.
• generate_data.py: Implements the tf.data pipeline that loads and preprocesses images before they reach the GPU.
• utils.py: Contains optimizer definitions (Adam, etc.) that maintain momentum buffers affecting memory usage.

Summary

• Default VRAM requirement: Training PFLD with --batch_size 64 and --image_size 112 requires approximately 2–3 GB of GPU memory.
• Aggressive allocation: The code sets per_process_gpu_memory_fraction=1.0 in train_model.py (line 124), forcing TensorFlow to reserve all available VRAM immediately.
• Memory reduction strategies: Reduce --batch_size, lower --image_size, or modify the GPU options fraction to train on hardware with limited VRAM (1–2 GB).
• Architecture efficiency: The MobileNet-V2 backbone keeps parameter count low (~5–7 MB), making PFLD suitable for edge devices and consumer GPUs despite the default memory allocation policy.

Frequently Asked Questions

What is the minimum GPU memory required to train PFLD?

You can train PFLD on a GPU with as little as 1–2 GB of VRAM by reducing the batch size to 16 or 32 and lowering the image resolution to 96×96 pixels. However, you must modify the per_process_gpu_memory_fraction setting in train_model.py (line 124) to prevent TensorFlow from attempting to allocate the entire GPU.

Why does PFLD use 100% of my GPU memory even with small batch sizes?

The training script explicitly configures TensorFlow to grab all available GPU memory via tf.GPUOptions(per_process_gpu_memory_fraction=1.0) at line 124 of train_model.py. This is a performance optimization to prevent memory fragmentation, but it causes the process to report high VRAM usage regardless of actual training needs. Change this value to 0.5 or use allow_growth=True to see true memory consumption.

How does input image size affect memory requirements in PFLD?

Memory usage scales roughly with the square of the image resolution because convolutional feature maps shrink or grow with spatial dimensions. Reducing --image_size from 112 to 96 pixels decreases activation memory by approximately 25%, while increasing to 128 pixels raises requirements significantly. The generate_data.py pipeline handles arbitrary square resolutions, so you can adjust this parameter without code changes.

Can I train PFLD on a CPU instead of a GPU?

While the repository is designed for TensorFlow GPU training, you can run train_model.py on a CPU by removing the GPU-specific session configuration at line 124 or setting CUDA_VISIBLE_DEVICES=-1. However, training will be substantially slower—expect hours or days per epoch compared to minutes on a GPU. For CPU-only environments, reduce --batch_size to 8 or 4 to fit within system RAM constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}