# Deep-Live-Cam Memory Management: How the max_memory Argument Controls RAM Usage

> Learn how DeepLiveCam manages RAM with the max memory argument. Prevent out-of-memory crashes and control resource usage during video processing.

- Repository: [Kenneth Estanislao/Deep-Live-Cam](https://github.com/hacksider/Deep-Live-Cam)
- Tags: internals
- Published: 2026-03-01

---

**Deep-Live-Cam caps RAM usage via the `--max-memory` CLI argument, which enforces platform-specific process limits to prevent out-of-memory crashes during high-resolution video processing.**

Deep-Live-Cam from the hacksider/Deep-Live-Cam repository implements deterministic memory management to prevent crashes when processing high-resolution video frames or running multiple inference models concurrently. The `max_memory` configuration system allows users to explicitly set RAM budgets across diverse hardware configurations, ensuring stable execution on everything from low-memory laptops to high-end GPU workstations.

## How Deep-Live-Cam Memory Management Works

### CLI Configuration and Global Storage

The memory management pipeline begins in [`modules/core.py`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/core.py), where the CLI defines the `--max-memory` argument with platform-specific defaults. The `suggest_max_memory()` function allocates **4 GB on macOS** and **16 GB on all other platforms**, accounting for different virtual memory architectures.

After parsing, the value propagates to `modules/globals.max_memory`, making the configuration available throughout the application lifecycle:

```python
import modules.globals as g

print(f"Configured max memory: {g.max_memory} GB")

```

### Resource Limiting Implementation

Before processing begins, the `limit_resources()` function in [`modules/core.py`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/core.py) configures two critical safeguards. First, it enables **TensorFlow GPU memory growth** to prevent the TensorFlow runtime from pre-allocating the entire GPU memory pool. Then, if `max_memory` is set, the function converts the gigabyte value to bytes using platform-specific calculations.

On macOS, the conversion applies a larger factor (`* 1024 ** 6`) because the underlying limit applies to virtual memory pages rather than physical RAM. On other platforms, the standard calculation (`* 1024 ** 3`) suffices.

### Cross-Platform Enforcement Mechanisms

The actual memory cap enforcement varies by operating system:

- **Windows**: `kernel32.SetProcessWorkingSetSize` forces the OS to maintain the process working-set within the requested byte range.
- **Linux/macOS**: `resource.setrlimit(RLIMIT_DATA, ...)` caps the maximum data segment size the process may allocate.

These system-level calls ensure that Deep-Live-Cam cannot exceed the configured RAM budget, regardless of how many frames or models are processed concurrently.

### Runtime Visibility

During execution, the configured memory limit appears in the tqdm progress bar for each batch of frames. In [`modules/processors/frame/core.py`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/processors/frame/core.py), the UI displays the current cap via the progress bar's `postfix` parameter, giving users real-time visibility into resource constraints.

## Technical Implications of the max_memory Argument

The `--max-memory` value directly impacts stability and performance across four scenarios:

**Value too low** (e.g., less than available RAM): The OS denies further memory allocations, causing `MemoryError` exceptions or early termination of frame-processing loops. Complex models may fall back to CPU inference or fail to load entirely.

**Value matches physical RAM**: This configuration keeps the process within safe bounds, prevents excessive swapping, and reduces the risk of OOM crashes while allowing full-resolution processing.

**Value exceeds physical RAM**: The OS compensates by swapping memory to disk, dramatically slowing processing speeds. On Windows, the working-set cap triggers aggressive paging despite the process limit.

**Unset (default)**: The program selects 4 GB on macOS or 16 GB elsewhere. While suitable for most consumer-grade machines, users with high-end GPUs or constrained laptops should override these defaults.

## Practical Configuration Examples

### Setting Memory Limits via CLI

Limit the process to 8 GB of RAM when processing video:

```bash
python run.py -s source.mp4 -t target.mp4 --max-memory 8

```

The option is parsed in [`modules/core.py`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/core.py) and stored globally in `modules/globals.max_memory`.

### Accessing Configuration in Python

Inspect the effective limit programmatically after initialization:

```python
import modules.globals as g

# Available after parse_args() executes

print(f"Active memory cap: {g.max_memory} GB")

```

### Programmatic Resource Control

For testing or custom pipelines, manually invoke the limiter:

```python
from modules.core import limit_resources
import modules.globals as g

# Set a conservative 2 GB limit for testing

g.max_memory = 2
limit_resources()  # Applies OS-specific caps immediately

```

The `limit_resources()` function contains the platform-specific logic for applying memory constraints based on the current `g.max_memory` value.

## Summary

- Deep-Live-Cam implements deterministic **memory management** through the `--max-memory` CLI argument, defaulting to 4 GB on macOS and 16 GB on other platforms.
- The `limit_resources()` function in [`modules/core.py`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/core.py) enforces caps using `SetProcessWorkingSetSize` on Windows and `setrlimit(RLIMIT_DATA)` on Linux/macOS.
- **macOS** uses a distinct byte calculation (`* 1024 ** 6`) compared to other platforms (`* 1024 ** 3`) due to virtual memory page differences.
- Configuring `max_memory` too low causes allocation failures, while values exceeding physical RAM trigger disk swapping and performance degradation.
- Users can monitor the active memory cap through the progress bar in [`modules/processors/frame/core.py`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/processors/frame/core.py) during video processing.

## Frequently Asked Questions

### What happens if I set --max-memory higher than my physical RAM?

The operating system compensates by swapping memory to disk, significantly slowing down Deep-Live-Cam's frame processing speed. On Windows, the `SetProcessWorkingSetSize` limit may still cap the working-set size while triggering aggressive paging, whereas Linux and macOS will allow allocation attempts until swap space exhausts.

### Why does Deep-Live-Cam default to 4 GB on macOS but 16 GB on other platforms?

According to the hacksider/Deep-Live-Cam source code, macOS utilizes a different virtual memory architecture where limits apply to memory pages rather than direct physical allocation. The `suggest_max_memory()` function accounts for this by recommending lower defaults that align with macOS's virtual memory management characteristics, while Windows and Linux receive higher defaults suitable for typical consumer hardware.

### Can I change the memory limit after the program has started?

While the CLI argument sets the initial value stored in `modules.globals.max_memory`, you can programmatically adjust it before calling `limit_resources()`. However, once the OS-level limits are applied via `SetProcessWorkingSetSize` or `setrlimit`, the process cannot increase its own cap without restarting, though it can further reduce allocation limits mid-execution.

### Does --max-memory affect GPU memory or only system RAM?

The `max_memory` argument primarily constrains system RAM through process-level limits. However, `limit_resources()` also configures TensorFlow GPU memory growth settings to prevent the runtime from pre-allocating the entire GPU memory pool. Dedicated GPU memory management depends on the underlying framework configuration rather than the `RLIMIT_DATA` or working-set restrictions applied to system RAM.