Mr.PlanB Logo

    Newsletter

    Subscribe our newsletter

    Get new infrastructure guides, comparison reports, and migration notes in your inbox.

    Infrastructure notes, guides, and new tools. Unsubscribe anytime.

    Back to Blog
    Proxmox
    GPU
    Homelab
    LLM

    Track Homelab VRAM with gputaskman on Proxmox

    November 13, 2026
    6 min read

    gputaskman is a terminal-based GPU monitoring utility that shows exactly which processes consume your video memory, breaking down allocations into model weights, compute buffers, and key-value cache. For a Proxmox homelab handling local AI inference alongside media transcoding, it clarifies where memory disappears across guest systems.

    Standard utilities often summarize memory without detail. On 3 November 2026, Microsoft VP Scott Hanselman launched the open-source project under the MIT license on GitHub. Per the GitHub API on 13 November 2026, the repository reached 2,882 stars, As reported by Tom's Hardware on 3 November 2026, Hanselman developed the tool to scratch a specific itch: to provide deeper insight into how memory is allocated rather than merely reporting a single total usage number.

    What gputaskman shows beyond nvidia-smi

    In a typical homelab environment, administrators frequently query hardware using basic commands. While tools like nvidia-smi report total memory usage and a raw list of running compute processes, they do not explain the internal allocation of that memory.

    The README for gputaskman describes the program as an htop equivalent for graphics hardware. It connects per-process memory allocations and engine activity with loaded model files, runtimes, and buffer splits. When monitoring a local large language model runner, such as an Ollama instance or llama-server, the terminal user interface breaks down memory into model weights, key-value (KV) cache, and dynamic compute buffers.

    Device and process counters are measurements. The classifications and GGUF-derived buffer breakdowns are calculated estimates. The documentation explicitly notes that the utility does not perform raw VRAM memory dumps or inspect internal game textures. Tom's Hardware quoted Hanselman describing the project as experimental software, meaning the interface and underlying feature sets continue to evolve rapidly.

    Where to run it on Proxmox

    Proxmox VE users frequently manage hardware by passing dedicated cards directly to virtual machines or sharing resources among lightweight environments. If you operate an AI homelab on Proxmox or run GPU resource pooling, it helps to know which guest is holding the memory.

    The official documentation does not mention Proxmox VE. Consequently, deciding where to run the tool depends entirely on your architectural setup:

    First, you can run the utility directly inside a Linux virtual machine that has full PCIe passthrough of an NVIDIA or AMD graphics card. Because the guest operating system has exclusive access to the card and shares a standard kernel process table, monitoring runs cleanly without translation layers.

    Second, you can execute it inside an LXC container or a Docker guest host that shares access to the underlying graphics nodes. The host still needs the GPU driver for the container to see the card, so check which processes the container can actually see (see the container caveat below).

    Third, because Proxmox VE is built on Debian, you could technically run the tool on the hypervisor host itself. However, installing additional third-party Python environments or binaries onto the base hypervisor host is entirely a personal administration choice. Many homelab operators prefer keeping the virtualization host completely clean to prevent potential package conflicts.

    Linux drivers and what each one reports

    Hardware telemetry collection varies depending on the vendor and the Linux kernel driver in use.

    On Linux with NVIDIA hardware, the tool communicates through NVML. It collects total memory, overall load, clock speeds, operating temperature, and board power consumption. It inspects process memory from NVML compute and graphics process lists, alongside per-process streaming multiprocessor, encoder, and decoder usage. Linux lacks equivalents for Windows WDDM commit counters, so spill and paged memory columns remain blank rather than displaying false zeroes. Processes owned by other system users require elevated sudo privileges to inspect completely.

    On native Linux systems running AMD graphics cards, the program uses the standard amdgpu kernel driver. It requires no ROCm installations, AMD SMI packages, or specialized runtime libraries. Device-level memory totals, GTT usage, temperatures, clock speeds, fan readings, and PCIe link states are read directly from sysfs and hwmon. Individual process allocations come from drm-resident-vram and drm-resident-gtt counters within proc files. GTT represents system RAM accessible to the graphics card, which populates the shared memory column. If a process uses user-mode queues through ROCm or HIP on /dev/kfd, its engine percentage shows as not available because the Linux kernel does not track individual process execution times on that interface, even though total VRAM remains accurate.

    Intel graphics support on Linux relies on the i915 kernel driver, using DRM file descriptor information. Device total VRAM on discrete Intel cards is estimated from the local memory PCI window, while overall usage is derived by summing client allocations. When telemetry counters require root access, such as specific performance monitoring unit counters under restricted paranoid system settings, the utility marks unreadable fields as unavailable rather than reporting zero.

    The container PID caveat

    Running workloads inside container runtimes like Docker or Kubernetes introduces a specific operational quirk that the documentation highlights.

    When running on NVIDIA hardware, NVML queries return process IDs that belong to the host system namespace. Inside an isolated container environment, those host numbers do not correlate with local container processes in the local process table. Furthermore, a standard container cannot inspect the host process table to resolve the mapping.

    The tool handles this discrepancy by analyzing the container process table for running tasks that have libcuda.so mapped into memory. While command-line tools like nvidia-smi open system device files directly, they do not map libcuda.so. The README explains that both PID namespaces number processes in creation order, so the program pairs unresolved NVML host IDs with local container processes by that order:

    • A process row marked with an asterisk indicates a matched process where the relative creation order aligns cleanly between the container and host namespaces.
    • A process row marked with a question mark indicates an estimated match, which occurs when NVML detects more active compute processes on the physical card than exist inside that specific container. This situation happens frequently when multiple containers share one physical GPU.
    • Processes running on the host that do not exist within the container, such as the host display server, are identified with an H prefix and are not inspected locally.

    During validation testing on a Vast.ai cloud Docker container running an RTX 3060 Ti on driver 580.82.09, the README reports that two PyTorch jobs running at startup, a third started while watching, and one that was killed were all matched to the right container PIDs with their memory sizes and live GPU load.

    Installation and requirements

    Portable Linux binaries published on the project releases page require glibc 2.35 or newer, which corresponds to Debian 12, Ubuntu 22.04, or subsequent distributions.

    You can run the precompiled release on a supported 64-bit Linux installation by downloading and unpacking the archive:

    tar -xzf gputaskman-VERSION-linux-x64.tar.gz
    cd gputaskman-VERSION-linux-x64
    ./gputaskman
    

    If you prefer installing through Python package managers without cloning source files, you can use uv or pipx:

    uv tool install gputaskman
    gputaskman
    

    Alternatively, you can run the command using pipx:

    pipx install gputaskman
    gputaskman
    

    On 13 November 2026, the project published release v0.4.1. Changes in this update included improvements for custom model-path detection, proper handling of Intel integrated memory counters, fixes for Snapdragon model identification, and clean reporting during recording failures.

    Knowing where memory goes helps when you size VMs, especially if you experiment with consumer vGPU configurations or test newer hardware where driver loading requirements demand close attention. Treat it as early software: run the portable build inside a test VM or container first, and keep it off the Proxmox host unless you have a reason to put it there.

    Frequently Asked Questions

    What is gputaskman?

    It is an open-source terminal GPU task manager created by Scott Hanselman that shows per-process VRAM consumption, GPU activity, active runtimes, and LLM memory breakdowns.

    Does gputaskman officially support Proxmox VE?

    No, the project documentation does not mention Proxmox VE. Users run it inside guest virtual machines, containers, or optionally on the Debian-based hypervisor host at their own choice.

    How does gputaskman handle GPU monitoring inside Docker containers?

    Because NVML reports host process IDs, gputaskman pairs unresolved host IDs with container processes that have libcuda.so mapped, based on process creation order.

    Which GPUs are supported on Linux systems?

    It supports NVIDIA graphics cards through NVML, AMD GPUs using the amdgpu driver, Intel graphics cards via the i915 driver, and Huawei Ascend 310P chips with npu-smi.

    What software requirements does gputaskman need on Linux?

    Portable Linux builds require glibc 2.35 or newer, which corresponds to Debian 12 or Ubuntu 22.04 or newer, along with an appropriate graphics driver.