`gc`

The Python gc module provides an interface to the language’s garbage collection facility. The collector is optional: it supplements the reference counting that Python always uses, cleaning up objects trapped in reference cycles. The module lets you enable or disable the collector, tune its performance, and debug memory leaks.

Here’s a quick example:

>>> import gc

>>> gc.collect()  # Output will depend on your current state
0

Key Features

Controls the garbage collection process
Provides access to garbage collection statistics
Enables debugging of memory leaks
Allows customization of garbage collection thresholds

Frequently Used Classes and Functions

Object	Type	Description
`gc.collect()`	Function	Forces a garbage collection
`gc.get_stats()`	Function	Returns a list of three per-generation dictionaries with collection statistics
`gc.set_debug()`	Function	Sets the garbage collection debugging flags
`gc.get_count()`	Function	Returns a tuple with the current collection counts
`gc.get_objects()`	Function	Returns a list of all objects tracked by the collector
`gc.set_threshold()`	Function	Sets the collection thresholds that control how often collection runs

Examples

Retrieving garbage collection statistics:

>>> gc.get_stats()  # One dictionary per generation, and numbers will vary
[{'collections': 4, 'collected': 140, 'uncollectable': 0},
 {'collections': 0, 'collected': 0, 'uncollectable': 0},
 {'collections': 0, 'collected': 0, 'uncollectable': 0}]

Enabling debugging of memory management:

>>> gc.set_debug(gc.DEBUG_LEAK)

gc.DEBUG_LEAK includes gc.DEBUG_SAVEALL, so unreachable objects are saved in gc.garbage for inspection rather than freed. Call gc.set_debug(0) to turn debugging back off when you’re done.

Enabling or disabling the garbage collector:

>>> gc.disable()
>>> gc.enable()

Common Use Cases

Forcing garbage collection in memory-constrained environments
Debugging memory leaks by examining uncollectable objects
Tuning garbage collection thresholds to optimize performance

Real-World Example

In a scenario where you suspect a memory leak in a Python application, you can use the gc module to inspect the objects trapped in reference cycles:

>>> import gc

>>> gc.set_debug(gc.DEBUG_SAVEALL)
>>> class Node:
...     def __init__(self):
...         self.self_ref = self
...

>>> node = Node()
>>> del node
>>> gc.collect()
1
>>> len(gc.garbage)
1

In this example, you tell the collector to stash every unreachable object in gc.garbage instead of freeing it, then trigger a collection cycle so you can inspect what the cycle detector found. By default, gc.garbage stays empty: since Python 3.4, objects with a __del__() method are collected normally, so you need gc.DEBUG_SAVEALL to populate the list.

Tutorial

Memory Management in Python

Get ready for a deep dive into the internals of Python to understand how it handles memory management. By the end of this article, you’ll know more about low-level computing, understand how Python abstracts lower-level operations, and find out about Python’s internal memory management algorithms.

intermediate python

For additional information on related topics, take a look at the following resources: