{"id":6041,"library":"ps-mem","title":"ps-mem: Per-Program Memory Usage Reporter","description":"ps-mem is a Python utility designed to accurately report the core memory usage per program on Linux, distinguishing itself from tools that report per-process. It calculates RAM usage by summing both private and shared memory across all processes belonging to a given program. The current stable version is 3.14, released in May 2022, and it operates as a command-line tool, primarily written in Python 3, though it also supported Python 2.","status":"active","version":"3.14","language":"en","source_language":"en","source_url":"https://github.com/pixelb/ps_mem","tags":["system-monitoring","memory-usage","linux","cli-tool"],"install":[{"cmd":"pip install ps-mem","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"ps-mem is primarily a command-line tool. While you can import and call its 'main' function, it is designed to parse command-line arguments (sys.argv) and print directly to sys.stdout. Programmatic interaction often involves running it as a subprocess to capture output or carefully mocking sys.argv and stdout for direct calls.","symbol":"main","correct":"import ps_mem\n# Then call ps_mem.main() after preparing sys.argv and redirecting stdout"}],"quickstart":{"code":"import subprocess\nimport os\n\n# Example 1: Run ps_mem as a command to get total memory usage\n# Note: ps_mem often requires root privileges for full accuracy.\n# This example tries without sudo first.\n\ntry:\n    # Using a common flag like -t for total or no flags for default output\n    result = subprocess.run(['ps_mem', '-t'], capture_output=True, text=True, check=True)\n    print(\"\\n--- ps_mem (total) output ---\")\n    print(result.stdout)\nexcept FileNotFoundError:\n    print(\"Error: 'ps_mem' command not found. Ensure it's installed and in your PATH.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running ps_mem: {e}\")\n    print(f\"Stderr: {e.stderr}\")\n    print(\"Note: ps_mem often requires root privileges. Try running with sudo if you encounter permission errors.\")\n\n# Example 2: Programmatic call to ps_mem's main function (more advanced, requires mocking)\n# This is illustrative and not typically recommended for simple use cases due to sys.argv/stdout manipulation.\nimport sys\nfrom io import StringIO\nfrom unittest.mock import patch\n\n# Assuming ps_mem is installed and available in your Python environment\ntry:\n    import ps_mem\n\n    # Capture stdout and mock sys.argv\n    captured_output = StringIO()\n    with patch('sys.argv', ['ps_mem', '-S']), \\\n         patch('sys.stdout', captured_output):\n        # Call the main function with desired arguments (e.g., -S for swap info)\n        # ps_mem.main() might call sys.exit(), so wrap it if needed or catch SystemExit.\n        try:\n            ps_mem.main()\n        except SystemExit as e:\n            if e.code != 0: # 0 means successful exit\n                print(f\"ps_mem.main() exited with error code {e.code}\")\n\n    output_from_main = captured_output.getvalue()\n    print(\"\\n--- ps_mem.main() programmatic output ---\")\n    print(output_from_main)\n\nexcept ImportError:\n    print(\"Error: 'ps_mem' module not found. Install with 'pip install ps-mem'.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during programmatic call: {e}\")","lang":"python","description":"The primary way to use ps-mem programmatically is to execute it as an external command using `subprocess`, mimicking its typical command-line usage. A more advanced method involves directly calling `ps_mem.main()`, but this requires careful handling of `sys.argv` and `sys.stdout`."},"warnings":[{"fix":"Execute the `ps_mem` command with `sudo` or ensure the script is run with appropriate permissions. For programmatic use via `subprocess`, ensure the command includes `sudo` if necessary, e.g., `subprocess.run(['sudo', 'ps_mem', ...])`.","message":"ps-mem typically requires root privileges (e.g., running with `sudo`) to accurately access `/proc/$pid/smaps` and other system files for comprehensive memory reporting.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Only use ps-mem on Linux systems. Consider cross-platform alternatives like `psutil` if OS compatibility is required.","message":"ps-mem is a Linux-specific utility due to its reliance on the `/proc` filesystem (e.g., `/proc/$pid/smaps`) for memory information. It will not work on other operating systems like macOS or Windows.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For most programmatic uses, consider running `ps_mem` as a subprocess and parsing its standard output. If direct import is necessary, be prepared to mock `sys.argv` and redirect `sys.stdout`.","message":"The library is primarily designed as a standalone command-line script, not a Python library with a traditional programmatic API of classes and functions. Directly importing `ps_mem` and calling internal functions like `ps_mem.main()` requires careful manipulation of `sys.argv` and `sys.stdout`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Understand that the tool aggregates memory usage by program name, not by individual process IDs, which is a key distinction from other memory reporting utilities like `ps`.","message":"The developer notes that the name 'ps_mem' is for backwards compatibility, and 'coremem' would be a more accurate description of what the tool does (reports core memory usage per *program*, not per *process*).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}