profiling package for organizing Python profiling toolsThis PEP proposes the creation of a new standard library module namedprofiling to organize Python’s built-in profiling tools under a single,coherent namespace.
This PEP also proposes the deprecation of theprofile module, a legacypure-Python tracing profiler.
Python currently ships with two tracing profilers:profile andcProfile. Theprofile module is implemented in pure Python and is largely educational or useful forsubclassing, but too slow for realistic use.cProfile, by contrast, is implementedin C and more suitable for practical profiling scenarios, although it is not a drop-inreplacement forprofile 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 interpreteroptimizations, such as those introduced byPEP 659. Moreover,cProfile only observes themain thread, making it less useful in modern concurrent Python programs. Confusingly, the namingof these modules implies thatprofile is canonical, when in fact it is largely obsolete.
With Python 3.15, a new sampling profiler was introduced underprofile.sample. Known astachyon, this tool uses statistical samplingto infer performance characteristics, which introduceszero overheadprofiling and works better with the modern Python interpreter. It alsosupportsmultiple threads, async functions, free threading builds andattaching to running processes. Despite these strengths, the placement oftachyon underprofile.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.
This reorganization addresses several long-standing issues with Python’s profiling tools.
First, it improvesdiscoverability by collecting all built-in profilersunder a single, clearly named namespace. Currently, profiling tools arescattered across modules with inconsistent naming and unclear relationships. Byintroducing theprofiling module, users will have a well-defined andintuitive location to explore and access profiling functionality.
Second, the proposal enhancesclarity by naming the submodules according totheir underlying methodology –profiling.tracing for deterministic tracingprofilers andprofiling.sampling for statistical sampling profilers. Thisexplicit categorization makes it easier to understand the behavior andlimitations of each tool and aligns the API with the mental model users areencouraged to adopt.
Third, it providesguidance to developers by making the recommended toolseasier to find and use. The current structure can mislead users into relying onoutdated or less performant modules likeprofile, simply because of namingprecedence. With theprofiling namespace and its clearer semantics, usersare more likely to choose the appropriate profiler for their specific use case,whether it involves low-overhead sampling or detailed tracing.
Finally, this structure promotesextensibility. By consolidating profilingtools under a unified namespace, it becomes straightforward to introduce futureprofiling capabilities – such as memory profilers, I/O profilers, or hybridtools – without overloading unrelated modules or adding redundant top-level names.Theprofiling module provides a natural home for this.
This PEP introduces a newprofiling module containing:
profiling.tracing: deterministic function-call tracing (relocated fromcProfile).profiling.sampling: the statistical sampling profiler (tachyon).ThecProfile implementation will be relocated toprofiling.tracing, withcProfileremaining as an alias for backwards compatibility. The tachyon sampling profiler will beavailable atprofiling.sampling.
profileTheprofile module will be deprecated starting in Python 3.15.
profile emits aDeprecationWarning.profile emit aDeprecationWarning.From Python 3.15,profiling.tracing will be preferred tocProfile &profile.
The code that, at the time of writing, is in theprofile.samplingmodule will be moved to theprofiling package.
The Python documentation will use the newprofiling module as the canonicalentry point for profiling functionality. It will also describe the distinction betweentracing and sampling profilers, and include guidance on when each type is most appropriate.
Documentation forcProfile will remain available but will link tothe newprofiling equivalents.
The only backwards incompatible aspect of this PEP is the future removal of theprofile modulebut this will be made following thePEP 387 procedure.
None.
cProfileRenamingcProfile toprofile.tracing was considered, but this change would impact alarge amount of existing code. Maintaining the original name while aliasing it underprofiling.tracing strikes a balance between compatibility and clarity.
profilers as the Module NameThe module was initially proposed asprofilers (plural) but was changed toprofiling(gerund form) based on community feedback. The gerund form is more consistent with otherPython standard library modules that represent categories of functionality.
An earlier version of this PEP proposed having the sampling profiler available under two names:profiling.sampling andprofiling.tachyon. This was rejected to avoid confusion - whenintroducing new functionality, it’s better to have a single, clear path to access it rather thanmultiple aliases. The nameprofiling.sampling was chosen as it clearly describes theprofiling methodology, while “tachyon” remains as an internal codename that may be mentionedin documentation.
tachyon ModuleIntroducingimporttachyon as a new top-level module was rejected. Grouping tachyon underprofiling helps establish a logical structure and prevents proliferation of top-level modulesand also minimizes the usage of global namespace as requested by the Python Steering Council.
This document is placed in the public domain or under the CC0-1.0-Universallicense, whichever is more permissive.
Source:https://github.com/python/peps/blob/main/peps/pep-0799.rst
Last modified:2025-11-07 04:32:09 GMT