PEP: 799
Title: A dedicated ``profiling`` package for organizing Python profiling tools
Author: Pablo Galindo Salgado <pablogsal@python.org>,
        László Kiss Kollár <kiss.kollar.laszlo@gmail.com>
Discussions-To: https://discuss.python.org/t/pep-799-a-dedicated-profilers-package-for-organizing-python-profiling-tool/100898
Status: Final
Type: Standards Track
Created: 21-Jul-2025
Python-Version: 3.15
Post-History: `01-Aug-2025 <https://discuss.python.org/t/pep-799-a-dedicated-profilers-package-for-organizing-python-profiling-tool/100898>`__
Resolution: `21-Aug-2025 <https://discuss.python.org/t/pep-799-a-dedicated-profilers-package-for-organizing-python-profiling-tool/100898/21>`__

.. canonical-doc:: :external+py3.15:mod:`profiling`

Abstract
========

This PEP proposes the creation of a new standard library module named
:mod:`!profiling` to organize Python's built-in profiling tools under a single,
coherent namespace.

This PEP also proposes the deprecation of the :mod:`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 ``profiling`` 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 -- ``profiling.tracing`` for deterministic tracing
profilers and ``profiling.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 ``profiling`` 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 ``profiling`` module provides a natural home for this.

Specification
=============

New Module Structure
--------------------

This PEP introduces a new ``profiling`` module containing:

- ``profiling.tracing``: deterministic function-call tracing (relocated from ``cProfile``).
- ``profiling.sampling``: the statistical sampling profiler (tachyon).

The ``cProfile`` implementation will be relocated to ``profiling.tracing``, with ``cProfile``
remaining as an alias for backwards compatibility. The tachyon sampling profiler will be
available at ``profiling.sampling``.

Deprecation of ``profile``
--------------------------

The ``profile`` module will be deprecated starting in Python 3.15.

- In Python 3.15: importing ``profile`` emits a ``DeprecationWarning``.
- In Python 3.16: all uses of ``profile`` emit a ``DeprecationWarning``.
- In Python 3.17: the module will be removed from the standard library.

From Python 3.15, :mod:`!profiling.tracing` will be preferred to :mod:`!cProfile` & :mod:`!profile`.

The code that, at the time of writing, is in the :mod:`!profile.sampling`
module will be moved to the :mod:`!profiling` package.

Documentation
=============

The Python documentation will use the new :mod:`!profiling` 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`` will remain available but will link to
the new ``profiling`` 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
=====================

Renaming ``cProfile``
---------------------

Renaming ``cProfile`` to ``profile.tracing`` was considered, but this change would impact a
large amount of existing code. Maintaining the original name while aliasing it under
``profiling.tracing`` strikes a balance between compatibility and clarity.

Using ``profilers`` as the Module Name
---------------------------------------

The module was initially proposed as ``profilers`` (plural) but was changed to ``profiling``
(gerund form) based on community feedback. The gerund form is more consistent with other
Python standard library modules that represent categories of functionality.

Multiple Names for the Sampling Profiler
-----------------------------------------

An earlier version of this PEP proposed having the sampling profiler available under two names:
``profiling.sampling`` and ``profiling.tachyon``. This was rejected to avoid confusion - when
introducing new functionality, it's better to have a single, clear path to access it rather than
multiple aliases. The name ``profiling.sampling`` was chosen as it clearly describes the
profiling methodology, while "tachyon" remains as an internal codename that may be mentioned
in documentation.

Top-Level ``tachyon`` Module
----------------------------

Introducing ``import tachyon`` as a new top-level module was rejected. Grouping tachyon under
``profiling`` helps establish a logical structure and prevents proliferation of top-level modules
and also minimizes the usage of global namespace as requested by the Python Steering Council.

Copyright
=========

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