Line-by-line profiler

Warnings

• breaking Python 3.6 and 3.7 support was removed in version 4.2.0. Users on these Python versions must use an older version of line-profiler or upgrade their Python interpreter.
  Fix: Upgrade Python to 3.8 or newer, or pin `line-profiler<4.2.0`.
• breaking Version 5.0.0 introduced potential speed regressions (fixed in 5.0.1) and specifically had issues with 'duplicate or inconsistent profiler output under Python 3.14 when multiprocessing is used.' This was fixed in 5.0.1.
  Fix: Upgrade to `line-profiler>=5.0.1` to mitigate performance issues and ensure correct multiprocessing output on Python 3.14+.
• gotcha Profiling inherently adds overhead to your code's execution. The measured times reflect the profiled execution, not necessarily the exact performance without profiling. Be mindful of this when interpreting results.
  Fix: Interpret profiling results as relative performance indicators rather than absolute benchmarks. Run multiple times to average out variations.
• gotcha line_profiler may produce unexpected or no results when profiling multi-threaded, multi-processing, or asynchronous (asyncio) code due to the nature of its tracing mechanism.
  Fix: For concurrent code, consider using profilers designed for such environments (e.g., `yappi` for multi-threading) or carefully isolate parts to profile one at a time.
• gotcha For programmatic control, directly calling `profiler.enable()` and `profiler.disable()` can be unsafe when nested. If you need nested profiling, use `profiler.enable_by_count()` and `profiler.disable_by_count()` instead.
  Fix: Replace `enable()/disable()` with `enable_by_count()/disable_by_count()` for robust nested profiling.
• gotcha When profiling Cython extensions built with relative paths, `line_profiler` might fail to display the original source code along with profiling results.
  Fix: Ensure Cython extensions are built with absolute paths for profiling builds, or investigate specific Cython build configurations that resolve this.

Install

• pip install line-profiler Standard installation
• pip install line-profiler[all] With optional dependencies (e.g., 'rich' for enhanced output)

Imports

• profile

  from line_profiler import profile

  While older versions and kernprof's default behavior could inject `@profile` into builtins, explicit import is the modern and recommended way since v4.1.0 for better script compatibility when not profiling.
• LineProfiler

  from line_profiler import LineProfiler

  Used for programmatic control of profiling.

Quickstart

Create a file named `my_script.py` with the code above. To profile, you can either set the `LINE_PROFILE=1` environment variable and run `python my_script.py`, or use the `kernprof` command-line tool. The `kernprof -lvr my_script.py` command is recommended to enable line-by-line profiling, view results directly in the console (verbose), and utilize rich formatting if available.

import time
from line_profiler import profile
import os

@profile
def slow_function_one():
    time.sleep(0.01)
    [x * x for x in range(1000)] # This line will be profiled

@profile
def slow_function_two(iterations):
    data = []
    for _ in range(iterations):
        data.append(sum(range(100)))
    time.sleep(0.02)

def main():
    print('Starting profiling demo...')
    slow_function_one()
    slow_function_two(1000)
    print('Profiling demo finished.')

if __name__ == '__main__':
    # Method 1: Run with environment variable (requires line_profiler to be imported and decorated)
    #   To run: LINE_PROFILE=1 python my_script.py
    #   Output will be printed to console and .lprof file generated.

    # Method 2: Run directly via kernprof CLI (recommended for explicit control)
    #   To run: kernprof -lvr my_script.py
    #   -l enables line-by-line profiling
    #   -v prints results to stdout
    #   -r enables rich output (if 'rich' is installed)

    # This block ensures the script is runnable even without explicit kernprof or env var
    if os.environ.get('LINE_PROFILE') == '1':
        main()
    else:
        # For direct execution without profiling enabled, or if kernprof handles execution
        main()