How to Limit Heap Size in Python?

In Python, memory management (including heap allocation) is handled automatically by the Python Memory Manager and Garbage Collector (GC).
Unlike low-level languages such as C or C++, Python does not expose direct APIs to manually set or cap heap size.

However, if you’re running applications in restricted environments (like containers, servers, or embedded systems), or debugging memory leaks, there are ways to limit memory and indirectly control heap usage.

This guide explains several approaches — using Python’s built-in resource module, shell limits (ulimit), environment variables, and container configurations.

What is Heap Memory in Python?

The heap is the area of memory used for dynamic allocation, where Python objects, variables, and data structures live. Python’s memory manager allocates memory chunks from the system and organizes them internally in blocks and pools.

While you can’t directly set a “heap size,” you can limit the total memory available to a Python process, which effectively limits its heap.

Method 1: Using resource Module (POSIX systems)

The resource module (available on Linux and macOS) lets you restrict system resources, including virtual memory (heap).

import resource
import sys

# Set maximum heap size (e.g., 500 MB)
max_heap_size = 500 * 1024 * 1024 # 500 MB in bytes

# Set memory limit using RLIMIT_AS (address space)
resource.setrlimit(resource.RLIMIT_AS, (max_heap_size, max_heap_size))

try:
 print("Allocating memory...")
 large_list = [0] * (10**8) # Simulate memory-heavy operation
except MemoryError:
 print("Memory limit reached! Exiting gracefully.")
 sys.exit(1)

print("Memory allocation successful within limit.")

Output (if limit exceeded):

Memory limit reached! Exiting gracefully.

How It Works

resource.setrlimit() sets a soft limit and hard limit on system resources.

The resource RLIMIT_AS represents the maximum address space (total virtual memory) the process can use.

When your Python process tries to allocate beyond this limit, it raises a MemoryError.

Parameter	Description
Soft limit	The current active limit (can be lowered or raised up to hard limit)
Hard limit	The maximum allowable limit (cannot exceed this without admin privileges)

This effectively limits Python’s heap, stack, and other allocations combined.

Notes –

> Works only on POSIX systems (Linux/macOS) — not available on Windows.
> If the allocation exceeds the cap, you get a MemoryError.
> Set values in bytes (e.g., 500 * 1024 * 1024 = 500 MB).
> Useful for sandboxing, testing, or controlled experiments.

Method 2: Using ulimit Command (Shell-level Limit)

On Linux and macOS, you can limit memory for any process, including Python, directly from the terminal using ulimit.

Steps:

1. Open your terminal.
2. Run:

ulimit -v 500000

→ This limits virtual memory to 500 MB (in kilobytes).

3. Then run your script:

python3 my_script.py

If Python exceeds the memory cap, it raises a MemoryError or is killed by the OS.

ulimit works per shell session — once you close the terminal, the limits reset.

Why Use ulimit?

> No code modification required
> Controls total memory (heap, stack, and mmap regions)
> Works for any executable, not just Python scripts.

Limitations:

> Only available on UNIX-like systems
> Doesn’t provide fine-grained control (affects all memory, not just heap)
> Not supported natively on Windows

Method 3: Using Environment Variables (Indirect Memory Control)

Although Python doesn’t provide an environment variable specifically for heap limits, you can combine debug allocators and system limits to monitor and restrict usage.

Example:

For Linux/macOS:

 export PYTHONMALLOC=debug 
# Enables Python memory allocator debugging 

ulimit -v 500000 # Limit memory to 500 MB 

python3 script.py

This helps detect excessive allocations, leaks, or fragmentation.

For Windows:

Windows doesn’t support ulimit. You can use Process Explorer or Windows Job Objects (win32 API) to restrict memory usage for a specific process.

Tools like Docker Desktop or Windows Subsystem for Linux (WSL) can also simulate such caps.

Method 4: Limiting Heap Size in Containers (Docker/Kubernetes)

If you’re running Python inside Docker or Kubernetes, you can limit heap size using container-level controls.

Example (Docker):

 docker run -m 512m --memory-swap 512m python:3.10 python3 script.py

-m 512m → sets memory limit (512 MB total)

The process inside the container (Python) can’t exceed this, and you’ll get MemoryError or an OOM kill if it tries.

This is the most robust way to limit heap memory in production.

Method 5: Manual Heap Management for Debugging (Optional)

For debugging memory leaks or controlling object creation, use Python’s introspection modules:

import gc
import tracemalloc

# Start memory tracing
tracemalloc.start()

# Simulate allocations
x = [i for i in range(1000000)]

# Display current and peak memory usage
current, peak = tracemalloc.get_traced_memory()
print(f"Current: {current / 10242:.2f} MB; Peak: {peak / 10242:.2f} MB")

# Clear unreferenced objects
gc.collect()

Output:

Current: 60.23 MB; Peak: 72.45 MB

This is great for understanding memory behavior, not for setting hard limits but helps identify where the heap grows.

Method 6: Using Third-Party Tools

If you need cross-platform heap control or monitoring:

Pympler – Memory profiling and size summaries for objects

memory_profiler – Line-by-line memory tracking

Heapy (from Guppy3) – Heap analysis and object inspection

psutil – Process-level memory usage monitoring

import psutil, os

process = psutil.Process(os.getpid())
print(f"Memory usage: {process.memory_info().rss / 1024 ** 2:.2f} MB")

Output:

Memory usage: 128.50 MB

import resource

# limit to 200 MB
soft, hard = 200 * 1024 * 1024, 200 * 1024 * 1024
resource.setrlimit(resource.RLIMIT_AS, (soft, hard))

# then run memory-allocating code

import subprocess, resource, os

def limit():
    resource.setrlimit(resource.RLIMIT_AS, (200*1024*1024, 200*1024*1024))

subprocess.Popen(['python', 'task.py'], preexec_fn=limit)

docker run --memory=256m my-python-image

[Service]
ExecStart=/usr/bin/python /opt/app/app.py
MemoryMax=256M

import psutil, os
p = psutil.Process(os.getpid())
print(p.memory_info().rss)  # resident set size in bytes