tracypy

A lightweight bridge from Python's sys.monitoring (PEP 669) to the Tracy profiler, as a plain-C extension module. Every Python function call becomes a Tracy zone, so you can see your program's call tree and timing in the Tracy viewer.

How it works

sys.monitoring delivers per-frame events; tracypy turns each frame's execution span into a Tracy zone. Entry events (PY_START / PY_RESUME / PY_THROW) begin a zone and exit events (PY_RETURN / PY_YIELD / PY_UNWIND) end it, pushed/popped on a per-thread stack. The callbacks are fast C functions; registration is the only part done in Python. Tracy is compiled in on-demand mode, so enabling tracypy is essentially free until a Tracy viewer connects.

The extension is built free-threading-ready (Py_MOD_GIL_NOT_USED), so it works on the free-threaded (no-GIL) builds of CPython too. Only Python function calls become zones — work inside C builtins or extension modules doesn't show up as its own zone. Each thread's zone stack is released when the process exits rather than when the thread does, so profiling a process that spawns unbounded short-lived threads grows memory slowly over time; for ordinary worker pools this is a non-issue.

Install

pip install tracypy        # or: uv pip install tracypy

Prebuilt wheels are published for CPython 3.13 and 3.14 (including the free-threaded 3.14t build) on Linux, macOS, and Windows, with the Tracy client statically linked — no toolchain or submodule needed. There is no source distribution, so on a platform or Python without a matching wheel, install from a Git checkout (below) instead.

From source

Building needs Python ≥ 3.13, a C/C++ toolchain, and CMake. The Tracy client is vendored as a git submodule, so clone recursively (or init the submodule), then install:

git submodule update --init        # if you didn't clone with --recurse-submodules
uv pip install .                   # or: pip install .

Usage

import tracypy

with tracypy.profile():
    my_workload()

Or run a script/module under the profiler without editing it:

python -m tracypy my_script.py [args...]
python -m tracypy -m my.module [args...]

profile() forwards its tool_id / name arguments to enable(). The low-level API is tracypy.enable(tool_id=PROFILER_ID, name="tracypy"), tracypy.disable(), and tracypy.is_enabled(). tracypy.is_connected() reports whether a Tracy viewer is currently attached — useful since on-demand capture records nothing until one connects.

A runnable demo lives in examples/demo.py — connect a viewer, then:

python -m tracypy examples/demo.py

Frames

Tracy frames delimit recurring units of work, so you can see per-unit timing statistics (min/max/avg, a frame-time graph) on top of the zone call tree. For web apps, for instance, a natural fit is "one frame per request":

import tracypy

# Discontinuous frame: an explicit span with a name of its own timeline.
with tracypy.frame("request"):
    handle(request)

For a Django app, drop in a middleware:

import tracypy

class TracyFrameMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        with tracypy.frame("request"):
            return self.get_response(request)

There's also a continuous-frame boundary marker, for the classic game-loop style where every tick is one frame:

tracypy.frame_mark()          # default frame boundary
tracypy.frame_mark("render")  # a named continuous frame

and the bare discontinuous primitives,

  • tracypy.frame_mark_start(name)
  • tracypy.frame_mark_end(name)

if the context manager doesn't fit.

Frame marks are independent of zone capture — they work whether or not enable() is on, and are inert until a viewer connects.

Viewing a trace

Download or build the Tracy profiler UI and Connect to localhost before (or while) your program runs. Because Tracy runs on-demand, nothing is captured until you connect.

tracypy vendors the Tracy client v0.13.1, so connect with a matching Tracy 0.13.x viewer — the network protocol is versioned, and a mismatched viewer won't connect.

On a clean exit tracypy flushes the buffered trace to a connected viewer automatically (via an atexit hook), so even short scripts don't lose their tail — just keep the viewer connected until the run finishes.

Project links

Data verified by PyPI on Jun 29, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for akx from gravatar.com akx

Credits

Maintainer: Aarni Koskela

GitHub Statistics

Data verified by PyPI on Jun 29, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.13

Tags

tracy profiler profiling sys.monitoring pep669 performance tracing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

tracypy-0.13.1.1-cp314-cp314t-win_amd64.whl (257.8 kB view details)

Uploaded CPython 3.14tWindows x86-64

tracypy-0.13.1.1-cp314-cp314t-win32.whl (253.9 kB view details)

Uploaded CPython 3.14tWindows x86

tracypy-0.13.1.1-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (212.7 kB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

tracypy-0.13.1.1-cp314-cp314t-macosx_11_0_arm64.whl (130.6 kB view details)

Uploaded CPython 3.14tmacOS 11.0+ ARM64

tracypy-0.13.1.1-cp314-cp314-win_amd64.whl (257.7 kB view details)

Uploaded CPython 3.14Windows x86-64

tracypy-0.13.1.1-cp314-cp314-win32.whl (253.8 kB view details)

Uploaded CPython 3.14Windows x86

tracypy-0.13.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (212.6 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

tracypy-0.13.1.1-cp314-cp314-macosx_11_0_arm64.whl (130.4 kB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

tracypy-0.13.1.1-cp313-cp313-win_amd64.whl (249.4 kB view details)

Uploaded CPython 3.13Windows x86-64

tracypy-0.13.1.1-cp313-cp313-win32.whl (247.0 kB view details)

Uploaded CPython 3.13Windows x86

tracypy-0.13.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (212.6 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

tracypy-0.13.1.1-cp313-cp313-macosx_11_0_arm64.whl (130.4 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

File details

Details for the file tracypy-0.13.1.1-cp314-cp314t-win_amd64.whl.

File metadata

  • Download URL: tracypy-0.13.1.1-cp314-cp314t-win_amd64.whl
  • Upload date:
  • Size: 257.8 kB
  • Tags: CPython 3.14t, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314t-win_amd64.whl
Algorithm Hash digest
SHA256 574b1ffd7a9fc7c713cc1b26b25a6f4a9195d3af7e68b0e5ada83002b28b7f83
MD5 45c70bb9314e06d834d2efc320ec14f7
BLAKE2b-256 df7b41dceb77b0079980041a3b9e6e456ba1bfe53957b9d0d59f3502fd056b66

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314t-win_amd64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp314-cp314t-win32.whl.

File metadata

  • Download URL: tracypy-0.13.1.1-cp314-cp314t-win32.whl
  • Upload date:
  • Size: 253.9 kB
  • Tags: CPython 3.14t, Windows x86
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314t-win32.whl
Algorithm Hash digest
SHA256 bce2802ed281ad2181a46a32b44445d9a4b84332f1aca55cd92487559ad67512
MD5 70ddb101152b038a11a6f6b7287bef50
BLAKE2b-256 8e1ea994cbc8b2266aef3faa12ca55cec52e2dc74974f299f5a60c2a6dcf08b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314t-win32.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e771a63458df25a6fd183a28c433e711b277e33568c27f393e2922b431cf2f0f
MD5 49fee14784f40f7822c47b0f198ab070
BLAKE2b-256 b9c0d7290466307a71252ffc368991e5af4705dff1f48b1612add40da6afce01

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp314-cp314t-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2a75f8d12bbae8d6ccaa829adb84118536a4bb0d38564ba7e30d5beb95755638
MD5 0a4ca48e406b441365c00e8f69164b63
BLAKE2b-256 96aabeff6a1efe949cd985629a745e32e4dad837bb7cfc8269eba5e2ffcd0a53

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314t-macosx_11_0_arm64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: tracypy-0.13.1.1-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 257.7 kB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 520f4fb942fe328838dbbe30933dac8a04fb1e624ef91ea4cdc6bcf64dc11855
MD5 0f86700fbbe7f9728595a0dd4681890a
BLAKE2b-256 688a1f30d8abfae9adcefb50a1d47f813ffad7bbcca2a4361c56f0f13b2dcac4

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314-win_amd64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp314-cp314-win32.whl.

File metadata

  • Download URL: tracypy-0.13.1.1-cp314-cp314-win32.whl
  • Upload date:
  • Size: 253.8 kB
  • Tags: CPython 3.14, Windows x86
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314-win32.whl
Algorithm Hash digest
SHA256 174c7c0c141a2e76eaa7e6105ad0b6d1b4ef06faa730d43d74de6d36110d7a1b
MD5 6e0c866e499cdce9d1eab6048009623d
BLAKE2b-256 129d3e9c39f6bea3a2fbc5bfe5ca2714436071bf0dc8cf1f063431d0669d8450

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314-win32.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 80dac42b9f3556e8db4ba82a2687556450f1776b0d0bd0e9ac8b05a0de9a56cf
MD5 c354f2bc1c72948bf9246caca3b73234
BLAKE2b-256 38dfaa13dd9a46296de35648c39121657482286620390b1cddf2961a14bca3f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tracypy-0.13.1.1-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 28d5c37cbc311fc1ae6e215f17bda875b0cd94bf1aa3ba17bcf877b2ab1726f7
MD5 c7e00538269f468c61bf4b2b5179cacf
BLAKE2b-256 6edd8b51109874379aa943d8ebfb17914fe22028e777ee6b035764f066886c72

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp314-cp314-macosx_11_0_arm64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: tracypy-0.13.1.1-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 249.4 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for tracypy-0.13.1.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 ba150b957c511df5f4473300b16535c2bc30014e787ca9273b8a27197c8d34cc
MD5 02b371f3875e05df52024df644b1dda4
BLAKE2b-256 c5084df9b45ed5ce0b018fbf3079a3e7ded26b33ed13eba19448d4b8c36cb6a5

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp313-cp313-win_amd64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp313-cp313-win32.whl.

File metadata

  • Download URL: tracypy-0.13.1.1-cp313-cp313-win32.whl
  • Upload date:
  • Size: 247.0 kB
  • Tags: CPython 3.13, Windows x86
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for tracypy-0.13.1.1-cp313-cp313-win32.whl
Algorithm Hash digest
SHA256 ca42152b3600cf3b37dd72fffdc4f818ebb0ae80271c287d3946cf444ca2e31e
MD5 89442587ce334664b4416b79e9a8c3f4
BLAKE2b-256 fa2ddf15b6958b0749fe588af4f2f0696a6b04b72a66b1e78485fc5ff833e7ab

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp313-cp313-win32.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for tracypy-0.13.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2000570746605b63fca75cfe1b7786ca90795c6da89045eb5b068b3745e88080
MD5 f6be267b4a83309f387161c2c5d5d757
BLAKE2b-256 96b378ddcc1a14b00c2f7fa7ccf5ea9788a11d74d2511b91d2cd9b24ca20d7fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tracypy-0.13.1.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tracypy-0.13.1.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 66d25dc1793ef301e910d1236d97bbb7240a78698c347c05bfa6b6544d9ad04f
MD5 9374d66ff2ca0b3ff6091e67ca77e914
BLAKE2b-256 a8918ab1db0cd0e6f85ee4e62e9ca0e4dc7c4278fd039722418b0c211df641e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for tracypy-0.13.1.1-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: ci.yml on akx/tracypy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page