plasma-umass/scalene

Scalene – Fast, line‑level CPU / GPU / memory profiling for Python

What it is – Scalene is a native‑code Python profiler that measures three things at once:

• CPU time (separating pure‑Python work from native library calls and system I/O),
• GPU time (for NVIDIA GPUs), and
• Memory usage (including per‑line allocation, copy volume and likely leaks).

It does this with a sampling approach that adds only ~10‑20 % overhead, so you can profile real workloads without instrumenting your code.

Why it matters – Most Python profilers either:

• instrument every line (slow), or
• give only function‑level data, or
• cannot tell you how much time is spent in C extensions or on the GPU. Scalene gives you line‑granular insight across CPU, GPU and memory, plus visual flame‑charts that stitch Python and native stacks together. This lets developers focus on the code they can actually change.

AI‑powered suggestions – After a profile is generated, Scalene can call an LLM (OpenAI, Azure, Bedrock, Ollama, etc.) to propose concrete optimizations for a highlighted line or region. You just click the lightning‑bolt (⚡) or explosion (💥) icon in the web UI, and the model returns a short suggestion that can be copied to the clipboard.

How you use it

• Install with pip install -U scalene or via Conda.
• Run from the command line: scalene run my_script.py (produces scalene-profile.json).
• View the results in a browser (scalene view) or directly in the terminal (scalene view --cli).
• Optional: use the VS Code extension to launch profiling and see the interactive UI inside the editor.
• You can also embed profiling calls programmatically (scalene_profiler.start()/stop()) or decorate specific functions with @profile.
• Configuration can be supplied via a YAML file (-c config.yaml).

Key features (as listed in the README)

Feature	What you get
Line‑level CPU profiling	Shows exact Python vs. native time per line, plus system I/O time.
GPU profiling	Reports NVIDIA GPU time (if present).
Memory profiling	Per‑line allocation, copy volume, leak detection, and Python vs. native memory split.
Async/await insight	Attributes wall‑clock await time to the line where a coroutine suspends, with concurrency stats.
Stitched Python + C stacks	Flame‑charts and timeline that combine Python frames with demangled C/C++ frames.
Reduced profiles	--reduced-profile limits output to lines that exceed configurable thresholds.
Multiprocessing & threading support	Works with the multiprocessing module and Python threads.
Free‑threaded Python (3.13t/3.14t) support	Full CPU + memory profiling on the upcoming free‑threaded interpreter.
Offline web UI	All assets are bundled; --standalone creates a single self‑contained HTML file.
AI optimization	Click‑to‑generate LLM suggestions from a variety of providers.

Typical workflow

1. scalene run my_app.py – profile the run.
2. scalene view – open the interactive GUI.
3. Inspect hot lines, memory‑leak candidates, or GPU bottlenecks.
4. Click the AI icon on a line to get a GPT‑4 (or other model) suggestion.
5. Apply the suggested change, re‑profile, and iterate.

Who should use it – Python developers who need high‑resolution performance data for data‑science notebooks, web services, scientific simulations, or any code that mixes pure Python, C extensions (NumPy, PyTorch, etc.) and optional GPU work. The AI suggestion layer is especially handy for teams that want quick, model‑driven hints without leaving the profiler.

---

Links

• PyPI: https://pypi.org/project/scalene/
• Conda‑forge: https://anaconda.org/conda-forge/scalene
• VS Code extension: https://marketplace.visualstudio.com/items?itemName=EmeryBerger.scalene
• Web UI demo: https://scalene-gui.github.io/scalene-gui/
• Talk (PyCon 2021): https://youtu.be/5iEf-_7mM1k