{"id":13572161,"url":"https://github.com/bloomberg/pystack","last_synced_at":"2026-01-26T01:14:32.506Z","repository":{"id":148378554,"uuid":"593714137","full_name":"bloomberg/pystack","owner":"bloomberg","description":"🔍 🐍 Like pstack but for Python!","archived":false,"fork":false,"pushed_at":"2025-03-25T16:14:55.000Z","size":1885,"stargazers_count":1075,"open_issues_count":15,"forks_count":46,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-03T14:18:39.161Z","etag":null,"topics":["coredump","python","python3","stacktrace","troubleshooting"],"latest_commit_sha":null,"homepage":"https://bloomberg.github.io/pystack","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-26T17:15:57.000Z","updated_at":"2025-04-03T11:20:48.000Z","dependencies_parsed_at":"2024-01-08T23:25:35.525Z","dependency_job_id":"954e5a0f-d7e3-46d4-968e-7f82248637df","html_url":"https://github.com/bloomberg/pystack","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fpystack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fpystack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fpystack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fpystack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/pystack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248272002,"owners_count":21075809,"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":["coredump","python","python3","stacktrace","troubleshooting"],"created_at":"2024-08-01T14:01:15.205Z","updated_at":"2026-01-26T01:14:32.469Z","avatar_url":"https://github.com/bloomberg.png","language":"C++","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/11718525/226942590-de015c9a-4d5b-4960-9c42-8c1eac0845c1.png\" width=\"70%\"\u003e\n\u003c/p\u003e\n\n______________________________________________________________________\n\n![OS Linux](https://img.shields.io/badge/OS-Linux-blue)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pystack)\n![PyPI - Implementation](https://img.shields.io/pypi/implementation/pystack)\n![PyPI](https://img.shields.io/pypi/v/pystack)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/pystack)\n[![Tests](https://github.com/bloomberg/pystack/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/bloomberg/pystack/actions/workflows/build_wheels.yml)\n![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)\n\n# PyStack\n\n\u003e Print the stack trace of a running Python process, or of a Python core dump.\n\nPyStack is a tool that uses forbidden magic to let you inspect the stack frames of a running Python\nprocess or a Python core dump, helping you quickly and easily learn what it's doing (or what it was\ndoing when it crashed) without having to interpret nasty CPython internals.\n\n# What PyStack can do\n\nPyStack has the following amazing features:\n\n- 💻 Works with both running processes and core dump files.\n- 🧵 Shows if each thread currently holds the Python GIL, is waiting to acquire it, or is currently\n  dropping it.\n- 🗑️ Shows if a thread is running a garbage collection cycle.\n- 🐍 Optionally shows native function calls, as well as Python ones. In this mode, PyStack prints\n  the native stack trace (C/C++/Rust function calls), except that the calls to Python callables are\n  replaced with frames showing the Python code being executed, instead of showing the internal C\n  code the interpreter used to make the call.\n- 🔍 Automatically demangles symbols shown in the native stack.\n- 📈 Includes calls to inlined functions in the native stack whenever enough debug information is\n  available.\n- 🔍 Optionally shows the values of local variables and function arguments in Python stack frames.\n- 🔒 Safe to use on running processes. PyStack does not modify any memory or execute any code in a\n  process that is running. It simply attaches just long enough to read some of the process's\n  memory.\n- ⚡ Optionally, it can perform a Python stack analysis without pausing the process at all. This\n  minimizes impact to the debugged process, at the cost of potentially failing due to data races.\n- 🚀 Super fast! It can analyze core files 10x faster than general-purpose tools like GDB.\n- 🎯 Even works with aggressively optimized Python interpreter binaries.\n- 🔍 Even works with Python interpreters' binaries that do not have symbols or debug information\n  (Python stack only).\n- 💥 Tolerates memory corruption well. Even if the process crashed due to memory corruption,\n  PyStack can usually reconstruct the stack.\n- 💼 Self-contained: it does not depend on external tools or programs other than the Python\n  interpreter used to run PyStack itself.\n\n## What platforms are supported?\n\nAt this time only Linux is supported.\n\n## Building from source\n\nIf you wish to build PyStack from source, you need the following binary dependencies in your\nsystem:\n\n- libdw\n- libelf\n\nNote that sometimes both libraries are provided together as part of a distribution's `elfutils`\npackage.\n\nCheck your package manager on how to install these dependencies (e.g.,\n`apt-get install libdw-dev libelf-dev` in Debian-based systems). Note that you may need to tell the\ncompiler where to find the header and library files of the dependencies for the build to succeed.\nIf `pkg-config` is available (e.g. `apt-get install pkg-config` on Debian-based systems), it will\nautomatically be used to locate the libraries and configure the correct build flags.\nCheck your distribution's documentation to determine the location of the header and library files\nor for more detailed information. When building on Alpine Linux (or any other distribution that\ndoesn't use glibc) you'll need elfutils 0.188 or newer. You may need to build this from source if\nyour distribution's package manager doesn't have it.\n\nOnce you have these binary dependencies installed, you can clone the repository and follow the\ntypical build process for Python libraries:\n\n```shell\ngit clone git@github.com:bloomberg/pystack.git pystack\ncd pystack\npython3 -m venv ../pystack-env/  # just an example, put this wherever you want\nsource ../pystack-env/bin/activate\npython3 -m pip install --upgrade pip\npython3 -m pip install -e .\npython3 -m pip install -r requirements-test.txt -r requirements-extra.txt\n```\n\nThis will install PyStack in the virtual environment in development mode (the `-e` of the last\n`pip install` command), and then install the Python libraries needed to test it, lint it, and\ngenerate its documentation.\n\nIf you plan to contribute back, you should install the pre-commit hooks:\n\n```shell\npre-commit install\n```\n\nThis will ensure that your contribution passes our linting checks.\n\n# Documentation\n\nYou can find the full documentation [here](https://bloomberg.github.io/pystack/).\n\n# Usage\n\nPyStack uses distinct subcommands for analyzing running processes and core dump files.\n\n```shell\nusage: pystack [-h] [-v] [--no-color] {remote,core} ...\n\nGet Python stack trace of a remote process\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --verbose\n  --no-color     Deactivate colored output\n\ncommands:\n  {remote,core}  What should be analyzed by PyStack (use \u003ccommand\u003e --help for a command-specific help section).\n    remote       Analyze a remote process given its PID\n    core         Analyze a core dump file given its location and the executable\n```\n\n## Analyzing running processes\n\nThe `remote` command is used to analyze the status of a running (remote) process. The analysis is\nalways done in a safe and non-intrusive way, as no code is loaded in the memory space of the\nprocess under analysis and no memory is modified in the remote process. This makes analysis using\nPyStack a great option even for those services and applications that are running in environments\nwhere the running process must not be impacted in any way (other than being temporarily paused,\nthough `--no-block` can avoid even that). There are several options available:\n\n```shell\nusage: pystack remote [-h] [-v] [--no-color] [--no-block] [--native] [--native-all] [--locals] [--exhaustive] pid\n\npositional arguments:\n  pid            The PID of the remote process\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --verbose\n  --no-color     Deactivate colored output\n  --no-block     do not block the process when inspecting its memory\n  --native       Include the native (C) frames in the resulting stack trace\n  --native-all   Include native (C) frames from threads not registered with the interpreter (implies --native)\n  --locals       Show local variables for each frame in the stack trace\n  --exhaustive   Use all possible methods to obtain the Python stack info (may be slow)\n```\n\nTo use PyStack, you just need to provide the PID of the process:\n\n```shell\n$ pystack remote 112\nTraceback for thread 112 [] (most recent call last):\n    (Python) File \"/test.py\", line 17, in \u003cmodule\u003e\n        first_func()\n    (Python) File \"/test.py\", line 6, in first_func\n        second_func()\n    (Python) File \"/test.py\", line 10, in second_func\n        third_func()\n    (Python) File \"/test.py\", line 14, in third_func\n        time.sleep(1000)\n```\n\n## Analyzing core dumps\n\nThe `core` subcommand is used to analyze the status of a core dump file. Analyzing core files is\nvery similar to analyzing processes but there are some differences, as the core file does not\ncontain the totality of the memory that was valid when the program was live. In most cases, this\nmakes no difference, as PyStack will try to adapt automatically. However, in some cases, you will\nneed to specify extra command line options to help PyStack locate the information it needs. When\nanalyzing cores, there are several options available:\n\n```shell\nusage: pystack core [-h] [-v] [--no-color] [--native] [--native-all] [--locals] [--exhaustive] [--lib-search-path LIB_SEARCH_PATH | --lib-search-root LIB_SEARCH_ROOT] core [executable]\n\npositional arguments:\n  core                  The path to the core file\n  executable            (Optional) The path to the executable of the core file\n\noptions:\n  -h, --help            show this help message and exit\n  -v, --verbose\n  --no-color            Deactivate colored output\n  --native              Include the native (C) frames in the resulting stack trace\n  --native-all          Include native (C) frames from threads not registered with the interpreter (implies --native)\n  --locals              Show local variables for each frame in the stack trace\n  --exhaustive          Use all possible methods to obtain the Python stack info (may be slow)\n  --lib-search-path LIB_SEARCH_PATH\n                        List of paths to search for shared libraries loaded in the core. Paths must be separated by the ':' character\n  --lib-search-root LIB_SEARCH_ROOT\n                        Root directory to search recursively for shared libraries loaded into the core.\n```\n\nIn most cases, you just need to provide the location of the core to use PyStack with core dump\nfiles:\n\n```shell\n$ pystack core ./the_core_file\nUsing executable found in the core file: /usr/bin/python3.8\n\nCore file information:\nstate: t zombie: True niceness: 0\npid: 570 ppid: 1 sid: 1\nuid: 0 gid: 0 pgrp: 570\nexecutable: python3.8 arguments: python3.8\n\nThe process died due receiving signal SIGSTOP\nTraceback for thread 570 [] (most recent call last):\n    (Python) File \"/test.py\", line 19, in \u003cmodule\u003e\n        first_func({1: None}, [1,2,3])\n    (Python) File \"/test.py\", line 7, in first_func\n        second_func(x, y)\n    (Python) File \"/test.py\", line 12, in second_func\n        third_func(x, y)\n    (Python) File \"/test.py\", line 16, in third_func\n        time.sleep(1000)\n```\n\n# License\n\nPyStack is Apache-2.0 licensed, as found in the [LICENSE](LICENSE) file.\n\n# Code of Conduct\n\n- [Code of Conduct](https://github.com/bloomberg/.github/blob/main/CODE_OF_CONDUCT.md)\n\nThis project has adopted a Code of Conduct. If you have any concerns about the Code, or behavior\nthat you have experienced in the project, please contact us at opensource@bloomberg.net.\n\n# Security Policy\n\n- [Security Policy](https://github.com/bloomberg/pystack/security/policy)\n\nIf you believe you have identified a security vulnerability in this project, please send an email\nto the project team at opensource@bloomberg.net, detailing the suspected issue and any methods\nyou've found to reproduce it.\n\nPlease do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports\nprivate until we've had an opportunity to review and address them.\n\n# Contributing\n\nWe welcome your contributions to help us improve and extend this project!\n\nBelow you will find some basic steps required to be able to contribute to the project. If you have\nany questions about this process or any other aspect of contributing to a Bloomberg open source\nproject, feel free to send an email to opensource@bloomberg.net and we'll get your questions\nanswered as quickly as we can.\n\n## Contribution Licensing\n\nSince this project is distributed under the terms of an [open source license](LICENSE),\ncontributions that you make are licensed under the same terms. For us to be able to accept your\ncontributions, we will need explicit confirmation from you that you are able and willing to provide\nthem under these terms, and the mechanism we use to do this is called a Developer's Certificate of\nOrigin [(DCO)](https://github.com/bloomberg/.github/blob/main/DCO.md). This is similar to the\nprocess used by the Linux kernel, Samba, and many other major open source projects.\n\nTo participate under these terms, all that you must do is include a line like the following as the\nlast line of the commit message for each commit in your contribution:\n\n```\nSigned-Off-By: Random J. Developer \u003crandom@developer.example.org\u003e\n```\n\nThe simplest way to accomplish this is to add `-s` or `--signoff` to your `git commit` command.\n\nYou must use your real name (sorry, no pseudonyms, and no anonymous contributions).\n\n## Steps\n\n- Create an Issue, select 'Feature Request', and explain the proposed change.\n- Follow the guidelines in the issue template presented to you.\n- Submit the Issue.\n- Submit a Pull Request and link it to the Issue by including \"#\u003cissue number\u003e\" in the Pull Request\n  summary.\n","funding_links":[],"categories":["Python","C++","语言资源库"],"sub_categories":["python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fpystack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fpystack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fpystack/lists"}