{"id":13586306,"url":"https://github.com/walles/px","last_synced_at":"2025-05-15T16:08:17.115Z","repository":{"id":5124008,"uuid":"50905707","full_name":"walles/px","owner":"walles","description":"ps, top and pstree for human beings","archived":false,"fork":false,"pushed_at":"2025-03-16T10:51:10.000Z","size":8863,"stargazers_count":279,"open_issues_count":19,"forks_count":12,"subscribers_count":7,"default_branch":"python","last_synced_at":"2025-05-11T02:57:15.027Z","etag":null,"topics":["command-line","command-line-tool","console","console-application","htop","ipc","linux","macos","osx","pex","pgrep","pipe","process-monitor","ps","pstree","python","python3","terminal","top","tui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/walles.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-02T08:27:50.000Z","updated_at":"2025-05-10T11:07:58.000Z","dependencies_parsed_at":"2024-03-10T15:32:01.067Z","dependency_job_id":"b674d18b-0779-4b16-97a7-1c7cc2ea25a3","html_url":"https://github.com/walles/px","commit_stats":{"total_commits":1113,"total_committers":6,"mean_commits":185.5,"dds":"0.014375561545372895","last_synced_commit":"8f52d01b4077714b2234675b7e7522bb42d12d08"},"previous_names":[],"tags_count":97,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walles%2Fpx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walles%2Fpx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walles%2Fpx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walles%2Fpx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/walles","download_url":"https://codeload.github.com/walles/px/tar.gz/refs/heads/python","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374475,"owners_count":22060611,"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":["command-line","command-line-tool","console","console-application","htop","ipc","linux","macos","osx","pex","pgrep","pipe","process-monitor","ps","pstree","python","python3","terminal","top","tui"],"created_at":"2024-08-01T15:05:27.812Z","updated_at":"2025-05-15T16:08:12.102Z","avatar_url":"https://github.com/walles.png","language":"Python","readme":"|Linux CI Status| |macOS CI Status|\n\n``ps``, ``top`` and ``pstree`` for Human Beings\n===============================================\n\nSee below for `how to install`_.\n\n``ptop`` is what I usually use when `LoadViz`_ shows something unexpected is\ngoing on.\n\n``px`` I use for figuring out things like \"do I still have any `Flutter`_\nprocesses running in the background\"?\n\n``pxtree`` can be used as ``watch --color pxtree brew`` to figure out what\n`Homebrew`_ is doing.\n\nOutput\n======\n\n``ptop``\n--------\n\nIf you're coming from ``htop`` or some other ``top`` variant, here's what to\nexpect from ``ptop``, with explanations below the screenshot:\n\n|ptop screenshot|\n\n* Note the core count right next to the system load number, for easy comparison.\n* Note the load history graph next to the load numbers. On this system the load\n  has been high for the last 15 minutes. This is a visualization of the numbers\n  you get from ``uptime``.\n* Note the bars showing which programs / users are using your memory below the\n  memory numbers\n* Note the ``IO Load`` number, showing which IO device had the highest average\n  throughput since ``ptop`` launched.\n* Note how the default sort order of CPUTIME-since-``ptop``-started makes the\n  display mostly stable and enables you to sort by CPU usage.\n* Note that binaries launched while ``ptop`` is running are listed at the bottom\n  of the display.\n* Note how the Python program on the second to last line is shown as\n  ``run_adapter.py`` (the program) rather than ``python3`` (the runtime). `This\n  support is available for many VMs`_ like Java, Node, ...\n* Selecting a process with Enter will offer you to see detailed information\n  about that process, in ``$PAGER``, `moar`_ or ``less``. Or to kill it.\n* After you press ``q`` to quit, the display is retained and some lines at the\n  bottom are removed to prevent the information you want from scrolling out of\n  view.\n* A help text on the bottom hints you how to search / filter (interactively),\n  change sort order or how to pick processes for further inspection or killing.\n\n``pxtree``\n----------\n\n|pxtree screenshot|\n\n* Note how search hits are highlighted in **bold**\n* Note how PIDs (process IDs) are printed by default\n* Note how multiple processes with the same names are coalesced and printed with\n  the count in parentheses\n* Note how the process names make sense (``lsp_server.py`` rather than ``python3``)\n\n``px``\n-------------\nRunning just ``px`` lists all running processes, with the most interesting ones last.\nOutput truncated for brevity.\n\n::\n\n   PID COMMAND                           USERNAME           CPU CPUTIME RAM COMMANDLINE\n     0 kernel                            root                --      --  -- kernel PID 0\n   273 SandboxHelper                     _coreaudiod         0%   0.01s  0% /System/Library/Frameworks/AudioToolbox.framework/XPCServices/com.apple.audio.SandboxHelper.xpc/Contents/MacOS/com.apple.audio.SandboxHelper\n   596 installerdiagd                    root                0%   0.01s  0% /System/Library/PrivateFrameworks/InstallerDiagnostics.framework/Versions/A/Resources/installerdiagd\n   983 periodic-wrapper                  root                0%   0.01s  0% /usr/libexec/periodic-wrapper daily\n     ...\n 57417 Google Chrome Helper              johan               0%   1m03s  2% /Applications/Google Chrome.app/Contents/Versions/70.0.3538.102/Google Chrome Helper.app/Contents/MacOS/Google Chrome Helper --type=renderer --field-trial-handle=5536258455526146518,14669732848005555331,131072 --service-pipe-token=7224348701576210538 --lang=sv --metrics-client-id=576E1A60-CA59-34F4-6C0C-57F64BD5F01C --enable-offline-auto-reload --enable-offline-auto-reload-visible-only --num-raster-threads=4 --enable-zero-copy --enable-gpu-memory-buffer-compositor-resources --enable-main-frame-before-activation --service-request-channel-token=7224348701576210538 --renderer-client-id=1119 --no-v8-untrusted-code-mitigations --seatbelt-client=418\n 14983 studio                            johan               0%   1h22m 14% /Applications/Android Studio.app/Contents/MacOS/studio\n 57993 kcm                               root                0%   0.02s  0% /System/Library/PrivateFrameworks/Heimdal.framework/Helpers/kcm --launchd\n 57602 Code Helper                       johan               0%  12.73s  2% /private/var/folders/cg/d7qzk4s13s9c8t49t3txdjpr0000gn/T/AppTranslocation/B5DDDD81-5A91-4961-B18B-20DAB3925EB0/d/Visual Studio Code.app/Contents/Frameworks/Code Helper.app/Contents/MacOS/Code Helper --type=renderer --js-flags=--nolazy --no-sandbox --primordial-pipe-token=570B948A976AACDA8EBB532E5680C83E --lang=sv --app-path=/private/var/folders/cg/d7qzk4s13s9c8t49t3txdjpr0000gn/T/AppTranslocation/B5DDDD81-5A91-4961-B18B-20DAB3925EB0/d/Visual Studio Code.app/Contents/Resources/app --node-integration=true --webview-tag=true --no-sandbox --background-color=#171717 --disable-blink-features=Auxclick --enable-pinch --num-raster-threads=4 --enable-zero-copy --enable-gpu-memory-buffer-compositor-resources --enable-main-frame-before-activation --content-image-texture-target=0,0,3553;0,1,3553;0,2,3553;0,3,3553;0,4,3553;0,5,3553;0,6,3553;0,7,3553;0,8,3553;0,9,3553;0,10,34037;0,11,34037;0,12,34037;0,13,3553;0,14,3553;0,15,3553;1,0,3553;1,1,3553;1,2,3553;1,3,3553;1,4,3553;1,5,3553;1,6,3553;1,7,3553;1,8,3553;1,9,3553;1,10,34037;1,11,34037;1,12,34037;1,13,3553;1,14,3553;1,15,3553;2,0,3553;2,1,3553;2,2,3553;2,3,3553;2,4,3553;2,5,3553;2,6,3553;2,7,3553;2,8,3553;2,9,3553;2,10,34037;2,11,34037;2,12,34037;2,13,3553;2,14,3553;2,15,3553;3,0,3553;3,1,3553;3,2,3553;3,3,3553;3,4,3553;3,5,34037;3,6,3553;3,7,3553;3,8,3553;3,9,3553;3,10,3553;3,11,3553;3,12,34037;3,13,3553;3,14,34037;3,15,34037;4,0,3553;4,1,3553;4,2,3553;4,3,3553;4,4,3553;4,5,34037;4,6,3553;4,7,3553;4,8,3553;4,9,3553;4,10,3553;4,11,3553;4,12,34037;4,13,3553;4,14,34037;4,15,34037 --service-request-channel-token=570B948A976AACDA8EBB532E5680C83E --renderer-client-id=110\n 57996 cat                               johan               0%    0.0s  0% cat\n 57745 GradleDaemon                      johan               0%  32.75s  3% /Library/Java/JavaVirtualMachines/jdk1.8.0_60.jdk/Contents/Home/bin/java -Xmx1536m -Dfile.encoding=UTF-8 -Duser.country=SE -Duser.language=sv -Duser.variant -cp /Users/johan/.gradle/wrapper/dists/gradle-4.6-all/bcst21l2brirad8k2ben1letg/gradle-4.6/lib/gradle-launcher-4.6.jar org.gradle.launcher.daemon.bootstrap.GradleDaemon 4.6\n\n* To give you the most interesting processes close to your next prompt, ``px``\n  puts last in its output processes that:\n\n  * Have been started recently (can be seen in the list as high PIDs)\n\n  * Are using lots of memory\n\n  * Have used lots of CPU time\n\n* Java processes are presented as their main class (``GradleDaemon``) rather\n  than as their executable (``java``). `This support is available for many VMs`_.\n\n``px java``\n-----------\nThis lists all Java processes. Note how they are presented as their main class\n(``GradleDaemon``) rather than as their executable (``java``). `This support is available for many VMs`_.\n\n::\n\n   PID COMMAND      USERNAME CPU CPUTIME RAM COMMANDLINE\n 57745 GradleDaemon johan     0%  35.09s  3% /Library/Java/JavaVirtualMachines/jdk1.8.0_60.jdk/Contents/Home/bin/java -Xmx1536m -Dfile.encoding=UTF-8 -Duser.country=SE -Dus\n\n``px _coreaudiod``\n------------------\nThis lists all processes owned by the ``_coreaudiod`` user.\n\n::\n\n PID COMMAND       USERNAME    CPU CPUTIME RAM COMMANDLINE\n 273 SandboxHelper _coreaudiod  0%   0.01s  0% /System/Library/Frameworks/AudioToolbox.framework/XPCServices/com.apple.audio.SandboxHelper.xpc/Contents/MacOS/com.apple.audio.SandboxHelper\n 190 DriverHelper  _coreaudiod  0%    0.3s  0% /System/Library/Frameworks/CoreAudio.framework/Versions/A/XPCServices/com.apple.audio.DriverHelper.xpc/Contents/MacOS/com.apple.audio.DriverHelper\n 182 coreaudiod    _coreaudiod  0%  11m28s  0% /usr/sbin/coreaudiod\n\n``sudo px 80727``\n-----------------\nThis shows detailed info about PID 80727.\n\n::\n\n  /Library/Java/JavaVirtualMachines/jdk1.8.0_60.jdk/Contents/Home/bin/java\n    -Xmx1536M\n    -Dfile.encoding=UTF-8\n    -Duser.country=SE\n    -Duser.language=sv\n    -Duser.variant\n    -cp\n    /Users/johan/.gradle/wrapper/dists/gradle-3.5-all/7s64ktr9gh78lhv83n6m1hq9u6/gradle-3.5/lib/gradle-launcher-3.5.jar\n    org.gradle.launcher.daemon.bootstrap.GradleDaemon\n    3.5\n\n  kernel(0)                root\n    launchd(1)             root\n  --\u003e GradleDaemon(80727)  johan\n\n  31m33s ago GradleDaemon was started, at 2017-06-18T13:47:53+02:00.\n  7.6% has been its average CPU usage since then, or 2m22s/31m33s\n\n  Other processes started close to GradleDaemon(80727):\n    -fish(80678) was started 9.0s before GradleDaemon(80727)\n    iTerm2(80676) was started 9.0s before GradleDaemon(80727)\n    login(80677) was started 9.0s before GradleDaemon(80727)\n    mdworker(80729) was started just after GradleDaemon(80727)\n    mdworker(80776) was started 21.0s after GradleDaemon(80727)\n\n  Users logged in when GradleDaemon(80727) started:\n    _mbsetupuser\n    johan\n\n  2017-06-18T14:19:26.521988: Now invoking lsof, this can take over a minute on a big system...\n  2017-06-18T14:19:27.070396: lsof done, proceeding.\n\n  Others sharing this process' working directory (/)\n    Working directory too common, never mind.\n\n  File descriptors:\n    stdin : [PIPE] \u003cnot connected\u003e (0x17d7619d3ae04819)\n    stdout: [CHR] /dev/null\n    stderr: [CHR] /dev/null\n\n  Network connections:\n    [IPv6] *:56789 (LISTEN)\n    [IPv6] *:62498 (LISTEN)\n\n  Inter Process Communication:\n    mDNSResponder(201): [unix] -\u003e0xe32cbd7be6021f1f\n\n  For a list of all open files, do \"sudo lsof -p 80727\", or \"sudo watch lsof -p 80727\" for a live view.\n\n* The command line has been split with one argument per line. This makes long\n  command lines readable.\n* The process tree shows how the Gradle Daemon relates to other processes.\n* Details on how long ago Gradle Daemon was started, and how much CPU it has been\n  using since.\n* A list of other processes started around the same time as Gradle Daemon.\n* A section describing where the standard file descriptors of the process go.\n* A list of users logged in when the Gradle Daemon was started.\n* A list of other processes with the same working directory as this one.\n* A list of network connections the process has open.\n* The IPC section shows that the Gradle Daemon is talking to ``mDNSResponder``\n  using `Unix domain sockets`_.\n\nThe IPC data comes from ``lsof``. ``sudo`` helps ``lsof`` get more detailed\ninformation; the command will work without it but might miss some information.\n\nKilling processes\n-----------------\nIf you want an interactive process killer using ``px`` and `fzf`_, you can make\na shell alias out of this:\n\n::\n\n  px --sort=cpupercent | fzf --bind 'ctrl-r:reload(px --sort=cpupercent)' --height=20 --no-hscroll --tac --no-sort --header-lines=1 | awk '{print $1}' | xargs kill -9\n\nType for fuzzy process search, use arrow keys to pick a process, Enter to kill,\nCTRL-R to refresh the process list.\n\nOr with previews for the currently selected process:\n\n::\n\n  px --sort=cpupercent --no-username | fzf --preview='px --color {1}' --bind 'ctrl-r:reload(px --sort=cpupercent --no-username)' --height=20 --no-hscroll --tac --no-sort --header-lines=1 | awk '{print $1}' | xargs kill -9\n\nInstallation\n------------\nOn `Debian 10 Buster`_ or later, and on `Ubuntu 19.04 Disco`_ and later, install using::\n\n  sudo apt install px\n\nIf you have `Homebrew`_ on your system (likely on macOS)::\n\n  brew install px\n\nOn `Arch Linux`_::\n\n  paru -S px_ptop\n\nOn other systems, install into ``/usr/local/bin`` by copy / pasting this command\ninto a terminal::\n\n  curl -Ls https://github.com/walles/px/raw/python/install.sh | bash\n\nOr you can install from Pypi. At least on macOS this can be problematic however,\nso ``brew`` or the above install script is still preferred::\n\n  sudo pip install --upgrade pxpx\n\nAfter installing you should be able to run ``px``, ``px --help`` or ``ptop``\nfrom the command line. Otherwise please verify that ``/usr/local/bin`` is in\nyour ``$PATH``.\n\nTo try ``px`` without installing it, just `download the latest px.pex`_,\n``chmod a+x px.pex``, then run ``./px.pex``.\n\nUsage\n-----\nJust type ``px`` or ``ptop``, that's a good start!\n\nTo exit ``ptop``, press \"``q``\".\n\nAlso try ``px --help`` to see what else ``px`` can do except for just listing all\nprocesses.\n\nIf you run into problems, try running with the ``--debug`` switch, it will print\ndebug logging output after ``px``/``ptop`` is done.\n\nDevelopment\n===========\n\nPrerequisites\n-------------\n\n* A Python 3.6+ version\n* `tox`_\n\nBuilding and Running\n--------------------\n\nNote that before editing any code, you need to run ``tox.sh`` once to create\nthe ``px/version.py`` file.\n\nNote that the build infrastructure here is designed to create a ``px.pex`` file\nthat works on \"all\" machines with Python 3 interpreters (tested on Linux and\nmacOS).\n\n* Clone: ``git clone git@github.com:walles/px.git ; cd px``\n* Build and test: ``./tox.sh``\n* Run: ``./px.pex``\n\nYou can also run ``./devbin/tox-in-docker.sh``, which can be used to run Linux\ntests on a Mac.\n\nReleasing a new Version\n-----------------------\nTo release a new version, run ``./devbin/release.sh`` and follow instructions.\n\nPerformance testing\n-------------------\n* Store the output of ``lsof -F fnaptd0i`` from a big system in lsof.txt.\n* ``./devbin/benchmark_ipcmap.py lsof.txt``\n\nKeeping this benchmark performant is important to be able to use ``px`` on big\nsystems.\n\nTo run it in a profiler, install `pyinstrument`_ and:\n\n* ``python3 -m pyinstrument ./devbin/benchmark_ipcmap.py lsof.txt``\n\nOr, to benchmark process listing:\n\n* ``pyinstrument -r html ./devbin/benchmark_proc_get_all.py``\n\nTODO ``top`` replacement\n------------------------\n\n* Disable terminal line wrapping for smoother handling of terminal window\n  resizes.\n\nTODO ``iotop`` replacement\n--------------------------\n\n* When given the ``--top`` flag and enough permissions, record per process IO\n  usage and present that in one or more columns.\n\nTODO misc\n---------\n\n* Details: When no users were found to be logged in at process start,\n  automatically detect whether it's because we don't have history that far back or\n  whether it seems to be that nobody was actually logged in. Inform the user about\n  the outcome.\n* In the px / top views, in the process owner column, maybe print other non-root\n  process owners of parent processes inside parentheses?\n* Ignore -E switch on Python command lines\n\n\nDONE\n----\n* Make ``px`` list all processes with PID, owner, memory usage (in % of available\n  RAM), used CPU time, full command line\n* Output should be in table format just like ``top`` or ``ps``.\n* Output should be truncated at the rightmost column of the terminal window\n* Output should be sorted by ``score``, with ``score`` being ``(used CPU time) *\n  (memory usage)``. The intention here is to put the most interesting processes on\n  top.\n* Each column should be wide enough to fit its widest value\n* Add a section about installation instructions to this document.\n* Add making-a-release instructions to this document\n* Add a ``.travis.yml`` config to the project that:\n\n  * OK: Runs ``flake8`` on the code\n  * OK: Tests the code on OS X\n  * OK: Tests the code on Linux\n\n* When piping to some other command, don't truncate lines to terminal width\n* If we get one command line argument, only show processes matching that string\n  as either a user or the name of an executable.\n* If we get something looking like a PID as a command line argument, show that\n  PID process in a tree with all parents up to the top and all children down. This\n  would replace ``pstree``.\n* If we get something looking like a PID as a command line argument, for that\n  PID show:\n\n  * A list of all open files, pipes and sockets\n  * For each pipe / domain socket, print the process at the other end\n  * For each socket, print where it's going\n\n* Doing ``px --version`` prints a ``git describe`` version string.\n* Add a column with the name of each running process\n* Put column headings at the top of each column\n* In the details view, list processes as ``Name(PID)`` rather than ``PID:Name``.\n  To humans the name is more important than the PID, so it should be first.\n* In the details view, list a number of processes that were created around the\n  same time as the one we're currently looking at.\n* Implement support for ``px --top``\n* If the user launches ``px`` through a symlink that's called something ending in\n  ``top``, enter ``top`` mode.\n* top: On pressing \"q\" to exit, redraw the screen one last time with a few less\n  rows than usual before exiting.\n* top: Print system load before the process listing.\n* Parse Java and Python command lines and print the name of the program being\n  executed rather than the VM.\n* In the details view, list users that were logged in when the process was\n  started.\n* In the details tree view, print process owners for each line\n* Print ``$SUDO_USER`` value with process details, if set\n* Run CI on both Python 2 and Python 3\n* In the details report, if the current process has a working directory that\n  isn't ``/``, list all other processes that have the same working directory.\n* ptop: Load bar: Set foreground color in green section to black, white on\n  green is hard to read.\n* ptop: Let user switch between CPU time sort and memory sort\n\n.. _how to install: #installation\n.. _LoadViz: https://github.com/walles/loadviz/\n.. _Flutter: https://flutter.dev\n.. _Debian 10 Buster: https://wiki.debian.org/DebianBuster\n.. _Ubuntu 19.04 Disco: https://launchpad.net/ubuntu/disco/\n.. _Homebrew: https://brew.sh\n.. _Arch Linux: https://archlinux.org/\n.. _download the latest px.pex: https://github.com/walles/px/releases/latest\n.. _Unix domain sockets: https://en.wikipedia.org/wiki/Unix_domain_socket\n.. _This support is available for many VMs: https://github.com/walles/px/blob/python/tests/px_commandline_test.py\n.. _moar: https://github.com/walles/moar\n.. _tox: https://pypi.org/project/tox/\n.. _pyinstrument: https://github.com/joerick/pyinstrument#installation\n.. _fzf: https://github.com/junegunn/fzf\n\n.. |Linux CI Status| image:: https://github.com/walles/px/actions/workflows/linux-ci.yml/badge.svg\n   :target: https://github.com/walles/px/actions/workflows/linux-ci.yml?query=branch%3Apython\n.. |macOS CI Status| image:: https://github.com/walles/px/actions/workflows/macos-ci.yml/badge.svg\n   :target: https://github.com/walles/px/actions/workflows/macos-ci.yml?query=branch%3Apython\n.. |ptop screenshot| image:: doc/ptop-screenshot.png\n.. |pxtree screenshot| image:: doc/pxtree-screenshot.png\n","funding_links":[],"categories":["Python","Packages"],"sub_categories":["CLI Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalles%2Fpx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwalles%2Fpx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalles%2Fpx/lists"}