line-profiler

library5.0.2pypypi✓ verified 24d ago

line_profiler is a module for doing line-by-line profiling of functions, providing detailed timing statistics for each line within selected functions. kernprof is a companion script that conveniently runs line_profiler or Python's standard library profilers. It is currently at version 5.0.2 and actively maintained, with a release cadence that includes regular bug fixes and feature enhancements.

testing

pip install line-profiler

github ↗package ↗

INSTALL

IMPORT

SIG · LINE-PROFILER

line-profiler

testingpythonv5.0.2

Install

6.9s avg

Import

151ms

Disk

105MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.163s · 27.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 6.9s · import 0.138s · 25MB

105MB installed

● package 105MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

profile

✓ from line_profiler import profile

✗ from __builtins__ 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.

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()

kernprof --version

Debug

Known issues

breakingPython 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`.

affects: <4.2.0

breakingVersion 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+.

affects: 5.0.0

gotchaProfiling 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.

affects: All

gotchaline_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.

affects: All

gotchaFor 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.

affects: All

gotchaWhen 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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'line_profiler'

The `line-profiler` package has not been installed in the Python environment you are currently using, or the environment is not correctly activated.

fix

Install the package using pip: `pip install line_profiler`

kernprof: command not found

The `kernprof` script, which is part of the `line-profiler` installation, is not in your system's PATH, or the installation was incomplete.

fix

Ensure `line_profiler` is installed (`pip install line_profiler`). If the issue persists, locate the `kernprof` executable (often in `~/.local/bin/` or a virtual environment's `bin` directory) and add its directory to your system's PATH, or run it directly using `python -m kernprof -l your_script.py`.

NameError: name 'profile' is not defined

The `@profile` decorator is being used in your script, but the `profile` object has not been injected into `__builtins__` by `kernprof`, or explicitly imported in your script.

fix

To fix this, either run your script with `kernprof -l your_script.py` (which injects `profile` globally), or for modern `line-profiler` versions (4.1.0+), import the decorator: `from line_profiler import profile` and ensure the `LINE_PROFILE=1` environment variable is set when running your script, or pass `--line-profile` to `python`.

ModuleNotFoundError: No module named 'line_profiler._line_profiler'

This often indicates an issue with the C extension compilation during installation or a version incompatibility, particularly for older `line-profiler` versions or specific Python environments.

fix

Try reinstalling `line-profiler` after cleaning up previous installations: `pip uninstall line_profiler` then `pip install --no-cache-dir --force-reinstall line_profiler`. Ensure you have a C compiler installed if installing from source on platforms where wheels are not available.

TypeError: 'module' object is not callable

This error typically occurs when `profile` is incorrectly imported as a module (e.g., `import profile`) instead of being defined as a decorator by `kernprof` or explicitly imported as a callable decorator.

fix

Ensure you are running your script via `kernprof -l your_script.py`, which globally injects the `@profile` decorator. If you are trying to use it programmatically, import it specifically as `from line_profiler import LineProfiler, profile` (with `profile` being the decorator) or avoid `import profile` if using `kernprof`.

Upgrade

Version history

5.0.2latest on PyPI · released Feb 23, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.8 or higher.

richoptionalOptional dependency for rich (highlighted) console output when using kernprof with '-r' flag.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/pyutils/line_profiler ↗

packagehttps://pypi.org/project/line-profiler/ ↗