Text of docs.python.org › 3.15 › library › profiling.sampling.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

profiling.sampling — Statistical profiler — Python 3.15.2 documentation

Navigation index modules | next | previous | Python » 3.15.2 documentation » The Python standard library » Debugging and profiling » profiling — Python profilers » profiling.sampling — Statistical profiler | Theme | profiling.sampling — Statistical profiler ¶ Added in version 3.15. Source code: Lib/profiling/sampling/ The profiling.sampling module, named Tachyon , provides statistical profiling of Python programs through periodic stack sampling.

Tachyon can run scripts directly or attach to any running Python process without requiring code changes or restarts. Because sampling occurs externally to the target process, overhead is virtually zero, making Tachyon suitable for both development and production environments. Tachyon follows earlier work on external sampling profilers such as Austin , py-spy , Pyflame , and rbspy . We thank their authors and the wider profiling community for their work and ideas.

What is statistical profiling? ¶ Statistical profiling builds a picture of program behavior by periodically capturing snapshots of the call stack. Rather than instrumenting every function call and return as deterministic profilers do, Tachyon reads the call stack at regular intervals to record what code is currently running. This approach rests on a simple principle: functions that consume significant CPU time will appear frequently in the collected samples.

By gathering thousands of samples over a profiling session, Tachyon constructs an accurate statistical estimate of where time is spent. The more samples collected, the more precise this estimate becomes. The following interactive visualization demonstrates how sampling profiling works. Press Play to watch a Python program execute, and observe how the profiler periodically captures snapshots of the call stack. Adjust the sample interval to see how sampling frequency affects the results.

How time is estimated ¶ The time values shown in Tachyon’s output are estimates derived from sample counts , not direct measurements. Tachyon counts how many times each function appears in the collected samples, then multiplies by the sampling interval to estimate time. For example, with a 10 kHz sampling rate over a 10-second profile, Tachyon collects approximately 100,000 samples. If a function appears in 5,000 samples (5% of total), Tachyon estimates it consumed 5% of the 10-second duration, or about 500 milliseconds.

This is a statistical estimate, not a precise measurement. The accuracy of these estimates depends on sample count. With 100,000 samples, a function showing 5% has a margin of error of roughly ±0.5%. With only 1,000 samples, the same 5% measurement could actually represent anywhere from 3% to 7% of real time. This is why longer profiling durations and shorter sampling intervals produce more reliable results—they collect more samples.

For most performance analysis, the default settings provide sufficient accuracy to identify bottlenecks and guide optimization efforts. Because sampling is statistical, results will vary slightly between runs. A function showing 12% in one run might show 11% or 13% in the next. This is normal and expected. Focus on the overall pattern rather than exact percentages, and don’t worry about small variations between runs.

When to use a different approach ¶ Statistical sampling is not ideal for every situation. For very short scripts that complete in under one second, the profiler may not collect enough samples for reliable results. Use profiling.tracing instead, or run the script in a loop to extend profiling time. When you need exact call counts, sampling cannot provide them. Sampling estimates frequency from snapshots, so if you need to know precisely how many times a function was called, use profiling.tracing .

When comparing two implementations where the difference might be only 1-2%, sampling noise can obscure real differences. Use timeit for micro-benchmarks or profiling.tracing for precise measurements. The key difference from profiling.tracing is how measurement happens. A tracing profiler instruments your code, recording every function call and return. This provides exact call counts and precise timing but adds overhead to every function call.

A sampling profiler, by contrast, observes the program from outside at fixed intervals without modifying its execution. Think of the difference like this: tracing is like having someone follow you and write down every step you take, while sampling is like taking photographs every second and inferring your path from those snapshots. This external observation model is what makes sampling profiling practical for production use.

The profiled program runs at full speed because there is no instrumentation code running inside it, and the target process is never stopped or paused during sampling—Tachyon reads the call stack directly from the process’s memory while it continues to run. You can attach to a live server, collect data, and detach without the application ever knowing it was observed. The trade-off is that very short-lived functions may be missed if they happen to complete between samples.

Statistical profiling excels at answering the question, “Where is my program spending time?” It reveals hotspots and bottlenecks in production code where deterministic profiling overhead would be unacceptable. For exact call counts and complete call graphs, use profiling.tracing instead. Quick examples ¶ Profile a script and see the results immediately: python -m profiling.sampling run script.py Profile a module with arguments: python -m profiling.sampling run -m mypackage.module arg1 arg2 Generate an interactive flame graph: python -m profiling.sampling run --flamegraph -o profile.html script.py Attach to a running process by PID: python -m profiling.sampling attach 12345 Print a single snapshot of a running process’s stack: python -m profiling.sampling dump 12345 Use live mode for real-time monitoring (press q to quit): python -m profiling.sampling run --live script.py Profile for 60 seconds with a faster sampling rate: python -m profiling.sampling run -d 60 -r 20khz script.py Generate a line-by-line heatmap: python -m profiling.sampling run --heatmap script.py Enable opcode-level profiling to see which bytecode instructions are executing: python -m profiling.sampling run --opcodes --flamegraph script.py Commands ¶ Tachyon operates through several subcommands. run and attach collect samples over time; dump captures a single snapshot; replay converts binary profiles to other formats.

The run command ¶ The run command launches a Python script or module and profiles it from startup: python -m profiling.sampling run script.py python -m profiling.sampling run -m mypackage.module When profiling a script, the profiler starts the target in a subprocess, waits for it to initialize, then begins collecting samples. The -m flag indicates that the target should be run as a module (equivalent to python -m ). Arguments after the target are passed through to the profiled program: python -m profiling.sampling run script.py --config settings.yaml The attach command ¶ The attach command connects to an already-running Python process by its process ID: python -m profiling.sampling attach 12345 This command is particularly valuable for investigating performance issues in production systems.

The target process requires no modification and need not be restarted. The profiler attaches, collects samples for the specified duration, then detaches and produces output. python -m profiling.sampling attach --live 12345 python -m profiling.sampling attach --flamegraph -d 30 -o profile.html 12345 On most systems, attaching to another process requires appropriate permissions. See Platform requirements for platform-specific requirements.

The dump command ¶ The dump command prints a single snapshot of a running process’s Python stack and exits, similar to a traceback: python -m profiling.sampling dump 12345 Unlike attach , dump does

The rest of this page is on the live site.