Skip to content

Austin: Python Sampling Profiler

by Tim Hopper · Markdown
Performance & Profiling AI Assistants

Austin is an external sampling profiler for CPython. It reads a running interpreter’s stacks without adding imports or decorators to the application, then saves samples for analysis in other tools.

Austin supports attaching to an existing process and launching a program under the sampler. The profiler comparison places it alongside py-spy, profiling.sampling, and Scalene.

Native-stack sampling briefly suspends target threads. Austin’s documentation advises avoiding native mode in production; its overhead differs from ordinary Python-stack sampling.

Select the measurement

Mode or option Recorded information
Default Wall-clock samples, including waiting threads
--cpu Samples of stacks running on a CPU
--memory Changes in resident memory between samples
--full Time, memory deltas, and thread CPU state
--gc Markers for samples collected during garbage collection
--where A snapshot of a running process’s thread stacks

--children includes child processes. Austin also samples subinterpreters, the independent interpreter instances that an application can create inside one process.

Memory mode measures resident-memory deltas, not individual allocations. Its attribution is less accurate in free-threaded Python, where concurrent threads make the source of a memory change ambiguous.

Check interpreter and platform support

The compatibility matrix covers CPython 3.10 through 3.15, including free-threaded builds. Austin runs on Linux, macOS, and Windows; supported architectures vary by platform.

Native mode supports Linux x86_64 and aarch64, macOS, and Windows x86_64. Windows native function names depend on available debugging symbols.

Process-inspection permissions also apply:

  • Linux attachment requires permission to inspect the target, documented as the CAP_SYS_PTRACE capability or root access. Docker containers need the corresponding SYS_PTRACE capability.
  • macOS requires root access. System Integrity Protection and executable signing restrict which Python installations Austin can inspect, even with root access.

The platform documentation describes these restrictions separately from interpreter-version support.

Inspect native stacks and asyncio tasks

--native interleaves native function frames with Python frames and includes threads created by native extensions. Resolving those frames identifies the C or C++ function behind a Python library call; a Python-only stack stops at the boundary.

For targets running CPython 3.14 or later, Austin records asyncio tasks and their await relationships. This includes suspended coroutine stacks, so a viewer can show which tasks wait for others.

Asyncio task tracking is unavailable in native mode. Task inspection and native unwinding require separate captures when both views are needed. The feature documentation details this limitation and the additional overhead of suspending threads.

Read the saved profile

Austin writes binary MOJO samples rather than an SVG or HTML report. The --output option selects a destination file; without a destination, binary data goes to standard output.

The Austin VS Code extension opens .mojo files directly and displays flame graphs with source annotations. The separate austin-python package provides conversion tools: mojo2austin produces collapsed stacks for flame-graph generators, while austin2speedscope produces Speedscope JSON.

MOJO output requires conversion before a text-based flame-graph generator can read it. The output documentation describes the formats and converters.

Query profiles with a coding agent

The Austin ecosystem has two interfaces for an AI coding agent to inspect recorded evidence:

Interface Dependency Results
MCP server Austin VS Code extension with a loaded profile Structured queries and actions in the shared flame-graph view
austin-query austin-python package Text tables or JSON for terminal agents and scripts

MCP, the Model Context Protocol, lets an agent call tools exposed by the editor. Austin’s tools return hot functions, call stacks, garbage-collection information, and task traces; other tools load a profile or focus the flame graph on a finding.

The query CLI answers similar questions without a running editor. Its queries include summaries, callers, and task trees; JSON output lets an agent inspect selected results instead of reading an entire binary recording.

Assess strengths and limits

  • External collection supports an existing process without application instrumentation.
  • The editor and query tools connect the same recording to visual inspection and agent analysis.
  • Sampling estimates time shares; it does not provide exact function-call counts, and short events may escape capture.
  • MOJO needs an Austin-compatible viewer or conversion step. Native-mode pauses and memory-delta attribution require separate interpretation.
Last updated on