To analyze memory consumption line-by-line, decorate the target function with @profile. You can then run your script using the memory_profiler module via the Python interpreter. This will output a table showing line numbers, memory usage, increments, occurrences, and the code content.

@profile
def my_func():
    a = [1] * (10 ** 6)
    b = [2] * (2 * 10 ** 7)
    del b
    return a

if __name__ == '__main__':
    my_func()

Run the analysis

$ python -m memory_profiler example.py

You can trigger the pdb debugger when a decorated function exceeds a specific memory threshold. Use the --pdb-mmem=X flag, where X is the threshold in MB.

$ python -m memory_profiler --pdb-mmem=100 my_script.py

To use the standard Python logging module (e.g., with RotatingFileHandler), redirect sys.stdout to a LogFile instance from the memory_profiler module.

>>> from memory_profiler import LogFile
>>> import sys
>>> sys.stdout = LogFile('memory_profile_log')

By default, mprof only tracks the parent process. To include child processes in a multiprocessing context, use one of the following:

1. Sum child memory into parent: Use the --include-children flag.
2. Track children independently: Use the --multiprocess flag to see individual rows for each child in the plot.

# Sum children memory with parent
mprof run --include-children <script>

# Track each child independently
mprof run --multiprocess <script>
mprof plot

Install the package via pip or conda-forge. You can also install from source after downloading the package.

$ pip install -U memory_profiler

You can redirect the output of the @profile decorator to a specific IO stream by passing the stream parameter. This is useful for writing profiling results directly to a file.

>>> fp=open('memory_profiler.log','w+')
>>> @profile(stream=fp)
>>> def my_func():
...     a = [1] * (10 ** 6)
...     b = [2] * (2 * 10 ** 7)
...     del b
...     return a

When using LogFile, you can control the verbosity of the output. For example, set reportIncrementFlag=False to exclude entries that only show memory increments, focusing instead on total usage.

>>> from memory_profiler import LogFile
>>> import sys
>>> sys.stdout = LogFile('memory_profile_log', reportIncrementFlag=False)

You can use the profile decorator directly in your code to enable line-by-line profiling without needing the -m memory_profiler command-line flag. You can also specify the decimal precision for the output.

from memory_profiler import profile

@profile(precision=4)
def my_func():
    a = [1] * (10 ** 6)
    b = [2] * (2 * 10 ** 7)
    del b
    return a

The memory_usage function returns the memory usage over a specified time interval.

Arguments:

• proc: The process to monitor. Can be a PID (use -1 for the current process), a string of Python code, or a tuple (f, args, kw) representing a function f to be executed with *args and **kw.

from memory_profiler import memory_usage

# Monitor current process for 1s with 0.2s intervals
mem_usage = memory_usage(-1, interval=.2, timeout=1)

# Monitor a specific function execution
def f(a, n=100):
    import time
    time.sleep(2)
    b = [a] * n
    time.sleep(1)
    return b

usage = memory_usage((f, (1,), {'n' : int(1e6)}))

The following commands are available for the mprof utility:

• mprof run: Run an executable and record memory usage.
• mprof plot: Plot recorded memory usage (defaults to the last recording).
• mprof list: List all recorded memory usage files.
• mprof clean: Remove all recorded memory usage files.
• mprof rm: Remove specific recorded memory usage files.

The profiler supports several backends for measuring memory:

• psutil (Default): Measures RSS (Resident Set Size).
• psutil_pss: Measures PSS (Proportional Set Size).
• psutil_uss: Measures USS (Unique Set Size).
• posix
• tracemalloc

You can specify the backend via the CLI or the memory_usage API.

# Via CLI
$ python -m memory_profiler --backend psutil my_script.py

# Via API
from memory_profiler import memory_usage
mem_usage = memory_usage(-1, interval=.2, timeout=1, backend="psutil")