{"id":17257833,"url":"https://github.com/p403n1x87/austin-tui","last_synced_at":"2025-05-14T15:07:08.855Z","repository":{"id":43875509,"uuid":"271632623","full_name":"P403n1x87/austin-tui","owner":"P403n1x87","description":"The top-like text-based user interface for Austin","archived":false,"fork":false,"pushed_at":"2025-03-27T08:29:32.000Z","size":6930,"stargazers_count":642,"open_issues_count":7,"forks_count":17,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-01T14:01:55.054Z","etag":null,"topics":["hacktoberfest","performance","profiling","python","tools","tui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/P403n1x87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"p403n1x87","patreon":"P403n1x87","custom":["https://www.buymeacoffee.com/Q9C1Hnm28","https://www.paypal.me/gtornetta/1"]}},"created_at":"2020-06-11T19:39:40.000Z","updated_at":"2025-03-27T08:27:59.000Z","dependencies_parsed_at":"2024-01-13T21:43:23.652Z","dependency_job_id":"eb510468-1cd8-4817-af2e-a23a6229fb3d","html_url":"https://github.com/P403n1x87/austin-tui","commit_stats":{"total_commits":38,"total_committers":6,"mean_commits":6.333333333333333,"dds":"0.26315789473684215","last_synced_commit":"d640de08c81e8c114370bf1bb01b8406e32b253d"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin-tui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin-tui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin-tui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin-tui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/P403n1x87","download_url":"https://codeload.github.com/P403n1x87/austin-tui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247878014,"owners_count":21011158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","performance","profiling","python","tools","tui"],"created_at":"2024-10-15T07:18:44.121Z","updated_at":"2025-04-08T16:00:14.451Z","avatar_url":"https://github.com/P403n1x87.png","language":"Python","funding_links":["https://github.com/sponsors/p403n1x87","https://patreon.com/P403n1x87","https://www.buymeacoffee.com/Q9C1Hnm28","https://www.paypal.me/gtornetta/1"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cbr\u003e\u003cimg src=\"art/logo.png\" alt=\"Austin TUI\" /\u003e\u003cbr\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eA Top-like Interface for Austin\u003c/h3\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/P403n1x87/austin-tui/actions?workflow=Tests\"\u003e\n    \u003cimg src=\"https://github.com/P403n1x87/austin-tui/workflows/Tests/badge.svg\"\n         alt=\"GitHub Actions: Tests\"\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003c!-- \u003ca href=\"https://travis-ci.org/P403n1x87/austin-tui\"\u003e\n    \u003cimg src=\"https://travis-ci.org/P403n1x87/austin-tui.svg?branch=master\"\n         alt=\"Travis CI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/P403n1x87/austin-tui\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/P403n1x87/austin-tui/branch/master/graph/badge.svg\"\n         alt=\"Codecov\"\u003e\n  \u003c/a\u003e --\u003e\n  \u003ca href=\"https://pypi.org/project/austin-tui/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/austin-tui.svg\"\n         alt=\"PyPI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/austin-tui/\"\u003e\n    \u003cimg src=\"https://static.pepy.tech/personalized-badge/austin-tui?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=downloads\"\n         alt=\"PyPI Downloads\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://anaconda.org/conda-forge/austin-tui\"\u003e\n    \u003cimg src=\"https://anaconda.org/conda-forge/austin-tui/badges/version.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://anaconda.org/conda-forge/austin-tui\"\u003e\n    \u003cimg src=\"https://anaconda.org/conda-forge/austin-tui/badges/downloads.svg\" /\u003e\n  \u003c/a\u003e\n  \n  \u003cbr/\u003e\n  \n  \u003ca href=\"https://github.com/P403n1x87/austin-tui/blob/master/LICENSE.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-GPLv3-ff69b4.svg\"\n         alt=\"LICENSE\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#synopsis\"\u003e\u003cb\u003eSynopsis\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#installation\"\u003e\u003cb\u003eInstallation\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#usage\"\u003e\u003cb\u003eUsage\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#compatibility\"\u003e\u003cb\u003eCompatibility\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#contribute\"\u003e\u003cb\u003eContribute\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca\n    href=\"https://www.buymeacoffee.com/Q9C1Hnm28\"\n    target=\"_blank\"\u003e\n  \u003cimg\n    src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\"\n    alt=\"Buy Me A Coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Synopsis\n\nThe Python TUI is a top-like text-based user interface for [Austin], the frame\nstack sampler for CPython. Originally planned as a sample application to\nshowcase [Austin] uses, it's been promoted to a full-fledged project thanks to\ngreat popularity.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui.gif\"\n       style=\"box-shadow: #111 0px 0px 16px;\"\n       alt=\"Austin TUI\" /\u003e\n\u003c/p\u003e\n\nThe header shows you the information of the application that is being profiled,\nlike its PID, the command line used to invoke it, as well as a plot of the\namount of CPU and memory that is being used by it, in a system-monitor style.\n\nTo know more about how the TUI itself was made, have a read through [The Austin\nTUI Way to Resourceful Text-based User Interfaces].\n\n# Installation\n\nAustin TUI can be installed directly from PyPI with\n\n~~~ console\npipx install austin-tui\n~~~\n\n\u003e **NOTE** In order for the TUI to work, the Austin 3 binary needs to be\n\u003e discoverable in the ways documented by the [austin-python] library. Have a\n\u003e look at [Austin installation] instructions to see how you can easily install\n\u003e Austin on your platform.\n\nOn macOS and Linux, Austin TUI and its dependencies (including Austin itself) \ncan be installed via conda with\n\n~~~ console\nconda install -c conda-forge austin-tui\n~~~\n\n# Usage\n\nOnce [Austin] 3 and Austin TUI are installed, you can start using them\nstraight-away. If you want to launch and profile a Python script, say\n`myscript.py`, you can do\n\n~~~ console\naustin-tui python3 myscript.py\n~~~\n\nor, if `myscript.py` is an executable script,\n\n~~~ console\naustin-tui ./myscript.py\n~~~\n\nLike [Austin], the TUI can also attach to a running Python application. To\nanalyse the frame stacks of all the processes of a running WSGI server, for\nexample, get hold of the PID of the parent process and do\n\n~~~ console\nsudo austin-tui -Cp \u003cpid\u003e\n~~~\n\nThe `-C` option will instruct [Austin] to look for child Python processes, and you\nwill be able to navigate through them with the arrow keys.\n\n\u003e The TUI is based on `python-curses`. The version included with the standard\n\u003e Windows installations of Python is broken so it won't work out of the box. A\n\u003e solution is to install the the wheel of the port to Windows from\n\u003e [this](https://www.lfd.uci.edu/~gohlke/pythonlibs/#curses) page. Wheel files\n\u003e can be installed directly with `pip`, as described in the\n\u003e [linked](https://pip.pypa.io/en/latest/user_guide/#installing-from-wheels)\n\u003e page.\n\n## Thread navigation\n\nProfiling data is processed on a per-thread basis. The total number of threads\n(across all processes, if sampling child processes) is displayed in the\ntop-right corner of the TUI. To navigate to a different thread, use the\n\u003ckbd\u003e\u0026larr;\u003c/kbd\u003e and \u003ckbd\u003e\u0026rarr;\u003c/kbd\u003e arrows. The PID and TID of the currently\nselected thread will appear in the middle of the top bar in the TUI.\n\n\n## Full mode\n\nBy default, Austin TUI shows you statistics of the last seen stack for each\nprocess and thread when the UI is refreshed (about every second). This is\nsimilar to what top does with all the running processes on your system.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui-normal-mode.png\"\n       style=\"box-shadow: #111 0px 0px 16px;\"\n       alt=\"Austin TUI - Default mode\" /\u003e\n\u003c/p\u003e\n\nIf you want to see all the collected statistics, with the frame stacks\nrepresented as a rooted tree, you can press \u003ckbd\u003eF\u003c/kbd\u003e to enter the _Full_\nmode. The last seen stack will be highlighted so that you also have that\ninformation available while in this mode.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui-full-mode.png\"\n       style=\"box-shadow: #111 0px 0px 16px;\"\n       alt=\"Austin TUI - Full mode\" /\u003e\n\u003c/p\u003e\n\nThe information that gets displayed is very dynamic and could become tricky to\ninspect. The current view can be paused by pressing \u003ckbd\u003eP\u003c/kbd\u003e. To resume\nrefreshing the view, press \u003ckbd\u003eP\u003c/kbd\u003e again. While the view is paused,\nprofiling data is still being captured and processed in the background, so that\nwhen the view is resumed, the latest figures are shown.\n\n\n## Graph mode\n\nA live flame graph visualisation of the current thread statistics can be\ndisplayed by pressing \u003ckbd\u003eG\u003c/kbd\u003e. This might help with identifying the largest\nframes at a glance.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui-flamegraph.gif\"\n       style=\"box-shadow: #111 0px 0px 16px;\"\n       alt=\"Austin TUI - Live flame graph\" /\u003e\n\u003c/p\u003e\n\nTo toggle back to the top view, simply press \u003ckbd\u003eG\u003c/kbd\u003e again.\n\n## Save statistics\n\nPeeking at a running Python application is nice but in many cases you would want\nto save the collected data for further offline analysis (for example, you might\nwant to represent it as a flame graph). At any point, whenever you want to dump\nthe collected data to a file, you can press \u003ckbd\u003eS\u003c/kbd\u003e and a file with all the\nsamples will be generated for you in the working directory, prefixed with\n`austin_` and followed by a timestamp. The TUI will notify of the successful\noperation on the bottom-right corner.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui-save.png\"\n       style=\"box-shadow: #111 0px 0px 16px;\"\n       alt=\"Austin TUI - Save notification\" /\u003e\n\u003c/p\u003e\n\nIf you run the Austin TUI inside VS Code, you can benefit from the editor's\nterminal features, like using \u003ckbd\u003eCtrl\u003c/kbd\u003e/\u003ckbd\u003eCmd\u003c/kbd\u003e+\u003ckbd\u003eLeft-Click\u003c/kbd\u003e\nto hop straight into a source file at a given line. You can also leverage the\nTUI's save feature to export the collected samples and import them into the\n[Austin VS Code] extension to also get a flame graph representation.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui-vscode.gif\"\n       style=\"box-shadow: #111 0px 0px 16px;\"\n       alt=\"Austin TUI\" /\u003e\n\u003c/p\u003e\n\n## Threshold\n\nThe statistics reported by the TUI might be overwhelming, especially in full\nmode. To reduce the amout of data that gets displayed, the keys \u003ckbd\u003e+\u003c/kbd\u003e and\n\u003ckbd\u003e-\u003c/kbd\u003e can be used to increase or lower the `%TOTAL` threshold\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui-threshold.png\"\n       style=\"box-shadow: #111 0px 0px 16px;\"\n       alt=\"Austin TUI - Threshold demonstration\" /\u003e\n\u003c/p\u003e\n\n\n# Compatibility\n\nAustin TUI has been tested with Python 3.7-3.10 and is known to work on\n**Linux**, **macOS** and **Windows**.\n\nSince Austin TUI uses [Austin] to collect samples, the same note applies here:\n\n\u003e Due to the **System Integrity Protection** introduced in **macOS** with El\n\u003e Capitan, Austin cannot profile Python processes that use an executable located\n\u003e in the `/bin` folder, even with `sudo`. Hence, either run the interpreter from\n\u003e a virtual environment or use a Python interpreter that is installed in, e.g.,\n\u003e `/Applications` or via `brew` with the default prefix (`/usr/local`). Even in\n\u003e these cases, though, the use of `sudo` is required.\n\nAs for Linux users, the use of `sudo` can be avoided by granting Austin the\n`cap_sys_ptrace` capability with, e.g.\n\n~~~ console\nsudo setcap cap_sys_ptrace+ep `which austin`\n~~~\n\n# Contribute\n\nIf you like Austin TUI and you find it useful, there are ways for you to\ncontribute.\n\nIf you want to help with the development, then have a look at the open issues\nand have a look at the [contributing guidelines](CONTRIBUTING.md) before you\nopen a pull request.\n\nYou can also contribute to the development of the Austin TUI by becoming a\nsponsor and/or by [buying me a coffee](https://www.buymeacoffee.com/Q9C1Hnm28)\non BMC or by chipping in a few pennies on\n[PayPal.Me](https://www.paypal.me/gtornetta/1).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/Q9C1Hnm28\"\n     target=\"_blank\"\u003e\n  \u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\"\n       alt=\"Buy Me A Coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n[Austin]: https://github.com/P403n1x87/austin\n[austin-python]: https://github.com/P403n1x87/austin-python#installation\n[Austin installation]: https://github.com/P403n1x87/austin#installation\n[Austin VS Code]: https://marketplace.visualstudio.com/items?itemName=p403n1x87.austin-vscode\n[The Austin TUI Way to Resourceful Text-based User Interfaces]: https://p403n1x87.github.io/the-austin-tui-way-to-resourceful-text-based-user-interfaces.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp403n1x87%2Faustin-tui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp403n1x87%2Faustin-tui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp403n1x87%2Faustin-tui/lists"}