gpufree 0.1.0

Quickly summarize free GPUs across SSH servers

gpufree

gpufree is a small CLI for checking free NVIDIA GPUs across servers listed in your SSH config. It runs nvidia-smi over SSH, queries hosts concurrently, and prints a compact summary by default.

$ gpufree
HOST  IDLE/TOTAL
----  ----------
4090  4/8
L40   0/4
5090  4/4

Use --detailed when you need the per-GPU table:

$ gpufree --detailed
HOST  GPU                        FREE/TOTAL       UTIL  TEMP  STATE  PROCS
----  -------------------------  ---------------  ----  ----  -----  --------------
4090  0 NVIDIA GeForce RTX 4090  24546/24564 MiB  0%    36C   idle   -
4090  1 NVIDIA GeForce RTX 4090  12000/24564 MiB  80%   52C   busy   python:12000MiB

Requirements

• Python 3.10+
• ssh available locally
• Passwordless SSH access to target hosts
• nvidia-smi available on target hosts

The package has no runtime Python dependencies.

Installation

From PyPI, after release:

pip install gpufree

For local development:

git clone https://github.com/raymondzhou/gpufree.git
cd gpufree
uv sync --dev
uv run gpufree

Usage

Check all default hosts from ~/.ssh/config:

gpufree

Check selected hosts:

gpufree 4090 L40

Filter default host discovery:

gpufree --include '*90'
gpufree --exclude 3090

If one SSH alias points to your current machine, exclude it permanently with an environment variable:

export GPUFREE_EXCLUDE=3090

Use JSON for scripts:

gpufree --json

Shell Completion

For zsh:

mkdir -p ~/.local/share/zsh/site-functions
gpufree --print-zsh-completion > ~/.local/share/zsh/site-functions/_gpufree

Make sure this directory is in fpath before compinit runs:

fpath=("$HOME/.local/share/zsh/site-functions" $fpath)

Restart zsh or run:

exec zsh

Host Discovery

When no hosts are passed explicitly, gpufree reads ~/.ssh/config and selects plain Host aliases. It skips wildcard aliases, github.com, entries with User git, and aliases that appear to point to the current machine unless --include-local is set.

Development

uv sync --dev
uv run pytest
uv run ruff check .
uv build

Build artifacts are written under dist/.