scalene

library2.3.0pypypi✓ verified 85d ago

Scalene is a high-resolution, low-overhead profiler for Python that analyzes CPU, GPU, and memory usage, providing AI-powered optimization suggestions. It's actively developed with frequent releases, typically addressing bug fixes, performance improvements, and compatibility updates for various Python versions and ecosystems.

devops observability ai-ml

pip install scalene

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SCALENE

scalene

devopspythonv2.3.0

Install

7.2s avg

Import

1092ms

Disk

121MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.0 · 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.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 7.2s · import 1.092s · 118MB

121MB installed

● package 121MB

Code

Verified usage

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

scalene_profiler

✓ from scalene import scalene_profiler

For programmatic control (start/stop) of the profiler. Most users will use the CLI directly.

Create a Python script (e.g., `my_script.py`) and then run Scalene from the command line using `python -m scalene my_script.py`. Scalene will generate a detailed profile in your terminal or an HTML report.

# my_script.py import time import math def calculate_heavy_stuff(n): result = 0 for _ in range(n): result += math.sin(math.sqrt(time.time())) return result def main(): print("Starting heavy calculations...") calculate_heavy_stuff(1000000) # Perform 1 million iterations print("Calculations finished.") if __name__ == "__main__": main() # To run the profiler from your terminal: # python -m scalene my_script.py

scalene --version

Debug

Known issues

gotchaScalene explicitly requires Python versions `!=3.11.0` and `>=3.8`. This means Python 3.11.0 is not supported, though 3.11.1+ should be fine.

fix

Ensure your Python environment is not 3.11.0. Upgrade to 3.11.1+ or use another compatible version (3.8, 3.9, 3.10, 3.12, etc.).

affects: All versions

breakingEarlier versions of Scalene (before 2.2.1) could crash with `SIGSEGV` when used with PyTorch Lightning on Python 3.12+ due to `sys.monitoring` tool ID conflicts.

fix

Upgrade to Scalene v2.2.1 or newer. This version includes a fix that handles conflicts by falling back to alternative tool IDs or the legacy `PyEval_SetTrace` tracer.

affects: <2.2.1

breakingTensorFlow 2.21+ changed `trace.enabled` from a callable to a boolean, causing compatibility issues with Scalene versions prior to 2.2.1.

fix

Upgrade to Scalene v2.2.1 or newer to ensure compatibility with TensorFlow 2.21 and later.

affects: <2.2.1

gotchaOn Windows, Scalene v2.1.x could experience extreme slowness and memory explosion during CPU profiling due to a hardcoded 1ms sampling interval, overriding the configured rate.

fix

Upgrade to Scalene v2.1.2 or newer to resolve this issue. Version 2.1.2 fixed the Windows timer loop to use the actual configured sampling rate.

affects: 2.1.0 - 2.1.1

gotchaThe primary and recommended way to use Scalene for profiling is via the command-line interface (`python -m scalene your_script.py`) or Jupyter magics (`%%scalene`). While a programmatic API exists, directly importing and calling functions to *run* the profiler in a general context is less common and might not capture the full execution scope as effectively.

fix

For general profiling, always prefer `python -m scalene <your_script.py> [args]` or use the Jupyter `%%scalene` magic. Use the programmatic API (`from scalene import scalene_profiler; scalene_profiler.start()`) for fine-grained control within specific code blocks.

affects: All versions

Errors

Common errors & fixes

scalene: command not found

The `scalene` executable is not located in any directory listed in your system's PATH environment variable, or it was not installed correctly.

fix

If not installed, run `pip install scalene`. If already installed, verify your PATH includes the directory where pip installs executables (e.g., `~/.local/bin` on Linux/macOS or the `Scripts` folder in a virtual environment).

ModuleNotFoundError: No module named 'scalene'

The `scalene` Python package is not installed in the currently active Python environment, or the environment from which you are trying to import it.

fix

Install Scalene using `pip install scalene` in the Python environment you intend to use.

fatal error: Python.h: No such file or directory

Scalene requires Python development headers (like `Python.h`) to compile its C extensions, and these headers are missing on your system.

fix

Install the appropriate Python development headers for your system. For Debian/Ubuntu: `sudo apt-get install python3-dev`. For Fedora: `sudo dnf install python3-devel`. On macOS, ensure Xcode command line tools are installed (`xcode-select --install`).

Segmentation fault (core dumped)

A critical low-level memory error, often stemming from an incompatibility with the Python version, specific system configurations, or a bug within Scalene's C extensions.

fix

Try upgrading Scalene to the latest version (`pip install --upgrade scalene`), ensure your Python version is officially supported, or test it in a clean virtual environment. If the issue persists, report it to the Scalene developers with detailed system information.

Upgrade

Version history

2.3.0latest on PyPI · released May 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/plasma-umass/scalene ↗

packagehttps://pypi.org/project/scalene/ ↗

homepagehttps://plasma-umass.org/scalene/ ↗