# austin-tui gives the Austin Python profiler a top-like terminal display

> austin-tui is a curses interface to Austin, the CPython frame stack sampler, showing CPU and memory plots per process plus a live flame graph view. It suits developers who want to watch a Python process while it runs rather than export a profile after the fact.

**P403n1x87/austin-tui** — The top-like text-based user interface for Austin

- Repository: https://github.com/P403n1x87/austin-tui
- Stars: 664 · Forks: 19
- Language: Python
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/p403n1x87-austin-tui

## A front end for a sampler, promoted out of sample status

The project describes itself in two layers. The Python TUI is a top-like text-based user interface for Austin, the frame stack sampler for CPython. Originally planned as a sample application to demonstrate Austin uses, it has been promoted to a full-fledged project thanks to great popularity. That origin story explains the shape of the tool. It was not designed as a profiler in its own right. It is a display surface for someone else's data, and every capability it has traces back to what Austin can sample. The consequence is a clean division of responsibility. Austin does the sampling and the TUI renders it, which means the TUI cannot profile a language Austin cannot sample, and it inherits Austin's overhead characteristics rather than trying to reduce them. The audience is a Python developer who wants to watch a process rather than read a report. The project topics place it plainly: performance, profiling, python, tools, tui, and it also carries a hacktoberfest tag, which says something about how contributions arrive. The repository holds austin_tui/ for the package, tests/, an art/ directory with the screenshots and the animated demonstration, and a pyproject.toml that identifies the package as austin-tui under GPL-3.0-or-later.

## The header works like a system monitor, one row per process

The default view is the part that makes the tool feel like top. The header shows the information of the application being profiled, such as its PID, the command line used to invoke it, and a plot of the amount of CPU and memory being used by it, in a system monitor style. By default Austin TUI shows statistics of the last seen stack for each process and thread when the UI refreshes, about every second, which the documentation compares to what top does with all the running processes on your system. Thread navigation is per thread, with the total number of threads across all processes, if child processes are being sampled, displayed in the top-right corner, and the left and right arrows move between threads while the PID and TID of the selected thread appear in the middle of the top bar. This is a small design point that matters more than it sounds. A sampled stack profiler is only useful if you can tell which thread you are looking at, because the interesting stack is usually in one worker out of many, and the TID in the top bar is what tells you whether you have found it.

## Full mode and the pause key exist because live data is hard to read

The documentation is candid that the information on screen is very dynamic and could become tricky to inspect, and the Full mode is the answer. Pressing F enters it, where the frame stacks are represented as a rooted tree rather than a summary, with the last seen stack highlighted so you keep that information while in the tree view. The other half of the answer is the pause key. Pressing P pauses the current view, and pressing it again resumes refreshing. The behaviour while paused is the detail that shows the design is deliberate. Profiling data is still being captured and processed in the background while the view is frozen, so when you resume, the latest figures are shown rather than a gap or a reset. The two modes answer different questions. Full mode is for reading the shape of a stack, and the default summary mode is for spotting which of several processes or threads just got expensive.

## The flame graph is a live view, not an export

Pressing G displays a live flame graph visualisation of the current thread statistics, and the documentation says this might help with identifying the largest frames at a glance. Pressing G again toggles back to the top view. This is the feature that distinguishes the tool from a conventional profiler, and it is worth being precise about why. A flame graph produced after the run is a static artefact of a sampled interval, and it is usually the better artefact for analysis, because you can read it, zoom it and compare it against a baseline. A live flame graph trades that for immediacy, and it is genuinely more useful in a specific situation, which is when you do not yet know where the time is going and you are watching the shape of the workload change under you as you poke at it. The two views are complementary rather than competing, and the fact that the TUI can save the collected data for offline analysis, which is the subject of the next section, closes the loop.

## Saving samples turns the live view into an offline artefact

Peeking at a running Python application is nice, but the documentation notes that in many cases you would want to save the collected data for further offline analysis, for example to represent it as a flame graph. Pressing S dumps the collected data to a file, generated in the working directory and prefixed with austin_. The important part is that this is a dump of everything collected so far, not a screenshot of the current view, so the artefact is not limited by whatever the display happened to show. That makes the workflow a two-stage one. You watch in the terminal while the process runs, notice where the cost is, and then export and analyse properly. It also means the TUI can be used in a lighter way, launched, left running, and harvested later, which is the shape of a long-running service that has an expensive warm-up phase.

## Installing it means installing Austin as well

Austin TUI is installed from PyPI with pipx:

```bash
pipx install austin-tui
```

On macOS and Linux, Austin TUI and its dependencies, including Austin itself, can be installed via conda:

```bash
conda install -c conda-forge austin-tui
```

The important caveat is stated right after the pipx route. For the TUI to work, the Austin 3 binary needs to be discoverable in the ways documented by the austin-python library, and the documentation points at the Austin installation instructions for how to get it on your platform. So there are two installs, not one, and the second one is a native binary that has to be findable by a specific mechanism rather than simply on your PATH. The Python dependencies listed in the package manifest reflect that split. austin-python at 2.1 is the binding to the sampler, importlib_resources at 5.10 handles resource lookup, lxml at 5.0 or newer is present, psutil covers process and system information, and there is a windows-curses dependency for Windows platforms, which is the next problem to talk about.

## Curses on Windows is the one place it will not just work

The TUI is based on python-curses, and the version included with standard Windows installations of Python is broken, so it will not work out of the box. The documented fix is to install the wheel of the port to Windows from the linked page, and wheel files can be installed directly with pip. This is a familiar pattern in the Python world, where the standard library ships a module that does not work on a particular platform and a third party port fills the gap, and the package manifest reflects it with the windows-curses entry for that platform only. On macOS and Linux the standard curses module is fine, which is why the conda route is offered specifically for those two platforms. The second practical constraint is the one that comes with sampling rather than with the interface. Attaching to a running process needs the permissions to read that process's memory, which is why attaching to a WSGI server's children is documented with sudo:

```bash
sudo austin-tui -Cp <pid>
```

The -C option tells Austin to look for child Python processes, and the arrow keys then move between them. Attaching to a process inside a container, or to a process owned by another user, needs the equivalent arrangements.

## Conclusion

Adopt austin-tui if you profile Python interactively and want to see CPU, memory and a live flame graph while a process runs, and you are comfortable with a terminal interface and a separate Austin binary to install. Do not adopt it for one-off profiling of a script that finishes quickly, where a file based report is more useful, and do not expect it to work on stock Windows without replacing the broken curses wheel. Before you start, confirm the Austin 3 binary is discoverable the way the austin-python library expects, install the Windows curses wheel if you are on that platform, and check that the container you run in can sample the target process.

## FAQ

### What is austin-tui and what does it show?

It is a top-like text-based user interface for Austin, the frame stack sampler for CPython. The header shows the PID, the command line and a system-monitor style plot of CPU and memory for the application being profiled, with statistics for the last seen stack of each process and thread, refreshed about every second.

### How do I install austin-tui?

From PyPI with `pipx install austin-tui`, or on macOS and Linux with `conda install -c conda-forge austin-tui`, which also brings in Austin itself. Either way the Austin 3 binary has to be discoverable in the ways the austin-python library documents, so there are two installs rather than one.

### How do I profile a script with austin-tui?

Run `austin-tui python3 myscript.py` for a script, or `austin-tui ./myscript.py` for an executable script. To attach to a running application, pass the parent process PID with the -C flag, for example `sudo austin-tui -Cp <pid>`, which also makes Austin look for child Python processes.

### What are the main display modes in austin-tui?

The default mode shows summary statistics per process and thread. Pressing F enters Full mode, where frame stacks appear as a rooted tree with the last seen stack highlighted, and pressing G toggles a live flame graph of the current thread. P pauses and resumes the refreshed view while data keeps being collected in the background.

### Does austin-tui work on Windows?

Not out of the box. The TUI is based on python-curses, and the version bundled with standard Windows Python installations is broken, so the documentation directs you to install the wheel of the Windows curses port, which can be installed directly with pip.

## Sources

- [Issues](https://github.com/P403n1x87/austin-tui/issues)
- [License: GPL-3.0](https://github.com/P403n1x87/austin-tui/blob/master/LICENSE)
- [P403n1x87/austin-tui on GitHub](https://github.com/P403n1x87/austin-tui)
- [README](https://github.com/P403n1x87/austin-tui/blob/master/README.md)
- [Releases](https://github.com/P403n1x87/austin-tui/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/p403n1x87-austin-tui