nprof -- naive profiler
Latest release: 0.6.1
ru README
nprof is a statistical Python profiler that tracks resource usage by a process and its child processes: CPU, RAM, and GPU.
nprof is not a function-level profiler: it measures resource consumption over time rather than Python function calls or individual lines of code.
It produces raw .csv and .json files, or formatted .txt, .md, and .html reports.
Installation
Python 3.9+:
# You can get it via PyPi
uv add nprof
# Download the .whl file from Releases
uv add ./nprof-0.3.0-py3-none-any.whl
# List GPUs available for profiling. Windows supports NVIDIA only;
# Linux also supports Intel.
uv run nprof gpus
Dependencies
psutil, nvidia-ml-py
For Intel GPU metrics on Linux, intel_gpu_top must be installed on the system. GPU monitoring can also be disabled entirely with gpu="none".
Quick start
# You can find this code in examples/quickstart.py
import time
from nprof import phase, profiling_start, profiling_stop, start, stop
profiling_start(
output="out/quickstart",
interval=0.005, # CPU + RSS: 5 ms
memory_interval=0.05, # USS + PSS: 50 ms
gpu_interval=0.1, # GPU: 100 ms
gpu="none", # Try "auto" to use the first available GPU
include_children=True,
sampler="process", # "thread" is also supported, but "process" is strongly recommended
html=True,
description="## Quick start. Include driver and software versions, test parameters, date and time, etc. here.",
)
try:
start() # Start of the interval of interest
try:
with phase("pipeline"): # Phases are inclusive: they include nested intervals
with phase("load"):
time.sleep(0.4)
with phase("compute"):
result = sum(i*i for i in range(4_000_000))
with phase("postprocess"):
time.sleep(0.2)
with phase("save"):
time.sleep(0.3)
finally:
stop() # End of the interval
finally:
report = profiling_stop() # Stop the sampler and write the reports
print(report["selection"]["duration_s"])
print(report["phase_summaries"]["pipeline"]["metrics"]["rss_mib"]["max"])
This creates quickstart.csv, .txt, and .html files.
The .html report is fully self-contained and includes easy-to-read charts. You can view the charts for each profiling phase separately.
API
profiling_start(output="results",interval=0.1,gpu="auto",include_children=True,html=True,json=False,md=False,*,description=None,description_file=None,sampler="thread",memory_interval=None,gpu_interval=None): starts the profiler and blocks until the first measurements are available.memory_interval=Noneandgpu_interval=Noneinherit the value ofinterval.profiling_stop() -> dict: stops profiling, saves the results, and returns a summary as a dictionary.start()/stop(): define the interval selected for the report. If omitted, the entire session after the profiler becomes ready is used.with phase("name"):: defines an entry/exit-based interval; nested intervals and repeated phase names are supported.mark("name"): starts a named segment. The nextmark(...)ends the previous one.mark("unmarked")disables the current segment marker.list_gpus(): lists GPUs and their backends; equivalent to thenprof gpusCLI command.
Sampling frequency
Some metrics (CPU/RSS) can be sampled many times per second without issues (for example, every 20 ms, or 0.02 s), while others (GPU/USS/PSS) cannot realistically be collected that frequently. For instance, intel_gpu_top updates its data only every 500 ms.
I recommend choosing the intervals individually. They are independent, and the .html report shows how closely the actual sampling intervals match the requested ones. For example, you might see:
CPU/RSS sampling | Target 0.010 s | Mean gap 0.015 s Max gap 0.047 s | P95 gap 0.031 s | Samples 952 | Mean cost 6.66 ms | Max cost 47.00 ms
This shows that although the requested interval was 10 ms, the actual mean interval was 15 ms.
Output formats
| Format | Contents |
|---|---|
.csv |
CPU/RSS samples from the selected interval, with sparse USS/PSS/GPU values and separate timestamps for slower metrics |
.json |
Run metadata, events, phase boundaries, inclusive summaries, and sampling quality |
.txt |
Human-readable tables and a list of samples |
.md |
Markdown tables for documentation |
.html |
Self-contained charts with interactive phase navigation |
Collected metrics
| Metric | Description |
|---|---|
cpu_pct |
CPU usage of tracked processes: 100% represents one fully utilized logical CPU core; values can exceed 100% |
cpu_time_s |
Accumulated CPU time since the baseline sample of the selected interval, including previously measured CPU time of child processes that have exited; not the absolute CPU time over a process's lifetime |
rss_mib |
Sum of RSS values; shared memory may be counted more than once |
uss_mib, pss_mib |
Process memory metrics available through psutil |
process_count |
Number of observed tracked processes in a sample |
gpu_device_* |
Device-wide GPU metrics; may include activity from unrelated processes |
gpu_process_vram_mib |
VRAM used by tracked NVIDIA/Intel compute processes, when available |
sample_duration_ms |
Duration of a complete sampling cycle (including slow measurements, if performed) |
memory_elapsed_s, gpu_elapsed_s |
Separate timestamps for less frequent USS/PSS and GPU measurements |
memory_sample_duration_ms, gpu_sample_duration_ms |
Duration of an individual expensive sampling operation; empty if the operation was not performed |
CLI and HTML
There is also a CLI, which is about as simple as a Socratic syllogism.
uv run nprof gpus # List GPUs available for profiling
uv run nprof view results.csv # Generate an .html report from a .csv file
uv run nprof view results.csv --open # Also open the report in the default browser
uv run nprof view results.csv --html # Also generates an .html report from a .csv file
uv run nprof view results.csv --no-html --md # Generate an .md report
Examples
HTML report previews generated by the examples in /examples/
License
Note that code is licensed under MPL 2.0
Metadata
Release files for nprof 0.6.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nprof-0.6.11.tar.gz | 34.4 kB | Without provenance | Details for nprof-0.6.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nprof-0.6.11-py3-none-any.whl | Python 3 | none | any | Details for nprof-0.6.11-py3-none-any.whl |
Total release size: 66.8 kB
Release files / nprof-0.6.11.tar.gz
| Download URL | nprof-0.6.11.tar.gz |
|---|---|
| Size | 34.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49523cd29e384556b31bda539c9fe5b2ac56bf7baa78098cf6ef522e8e119d97
|
|
BLAKE2b-256 checksum How to use checksums |
a65fe70d4a5ff87b53357caa1e661945942c14a2f5e9da13c1ec07ba60bd591c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / nprof-0.6.11-py3-none-any.whl
| Download URL | nprof-0.6.11-py3-none-any.whl |
|---|---|
| Size | 32.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67fb6a7e7fbd004f81c0c6da6393aaf2d990ba6d1aaa8ae1c263ba205da365c1
|
|
BLAKE2b-256 checksum How to use checksums |
394ba30d9384f6d4a95a0e8a95f694e5a05faba88a74e3bd644208f5b39ba906
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for nprof 0.6.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.