Abstract

This PEP proposes the creation of a new standard library module named profilers to organize Python’s built-in profiling tools under a single, coherent namespace.

This PEP also proposes the deprecation of the profile module, a legacy pure-Python tracing profiler.

Motivation

Python currently ships with two tracing profilers: profile and cProfile. The profile module is implemented in pure Python and is largely educational or useful for subclassing, but too slow for realistic use. cProfile, by contrast, is implemented in C and more suitable for practical profiling scenarios, although it is not a drop-in replacement for profile due to some behavioral differences.

Both of these are tracing profilers, meaning they instrument every function call and return. This methodology introduces significant runtime overhead and can disable certain interpreter optimizations, such as those introduced by PEP 659. Moreover, cProfile only observes the main thread, making it less useful in modern concurrent Python programs. Confusingly, the naming of these modules implies that profile is canonical, when in fact it is largely obsolete.

With Python 3.15, a new sampling profiler was introduced under profile.sample. Known as tachyon, this tool uses statistical sampling to infer performance characteristics, which introduces zero overhead profiling and works better with the modern Python interpreter. It also supports multiple threads, async functions, free threading builds and attaching to running processes. Despite these strengths, the placement of tachyon under profile.sample is misleading and obscures its importance.

Currently, the organization of profiling tools lacks a consistent, discoverable structure. The proposed reorganization is meant to guide users more effectively toward appropriate tools, clarify methodological distinctions between profilers, and lay the groundwork for future extensions.

Rationale

This reorganization addresses several long-standing issues with Python’s profiling tools.

First, it improves discoverability by collecting all built-in profilers under a single, clearly named namespace. Currently, profiling tools are scattered across modules with inconsistent naming and unclear relationships. By introducing the profilers module, users will have a well-defined and intuitive location to explore and access profiling functionality.

Second, the proposal enhances clarity by naming the submodules according to their underlying methodology – profilers.tracing for deterministic tracing profilers and profilers.sampling for statistical sampling profilers. This explicit categorization makes it easier to understand the behavior and limitations of each tool and aligns the API with the mental model users are encouraged to adopt.

Third, it provides guidance to developers by making the recommended tools easier to find and use. The current structure can mislead users into relying on outdated or less performant modules like profile, simply because of naming precedence. With the profilers namespace and its clearer semantics, users are more likely to choose the appropriate profiler for their specific use case, whether it involves low-overhead sampling or detailed tracing.

Finally, this structure promotes extensibility. By consolidating profiling tools under a unified namespace, it becomes straightforward to introduce future profiling capabilities – such as memory profilers, I/O profilers, or hybrid tools – without overloading unrelated modules or adding redundant top-level names. The profilers module provides a natural home for this.

Specification

Documentation

The Python documentation will use the new profilers module as the canonical entry point for profiling functionality. It will also describe the distinction between tracing and sampling profilers, and include guidance on when each type is most appropriate.

Documentation for cProfile and profile.sample will remain available but will link to the new profilers equivalents.

Backwards Compatibility

The only backwards incompatible aspect of this PEP is the future removal of the profile module but this will be made following the PEP 387 procedure.

Security Implications

None.

Rejected Alternatives

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.