Metadata-Version: 2.4
Name: gpufree
Version: 0.1.0
Summary: Quickly summarize free GPUs across SSH servers
Keywords: gpu,ssh,nvidia-smi,cluster,cli
Author: Raymond
Author-email: Raymond <1138541250@qq.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/raymondzhou/gpufree
Project-URL: Issues, https://github.com/raymondzhou/gpufree/issues
Description-Content-Type: text/markdown

# 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.

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

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

```console
$ 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:

```bash
pip install gpufree
```

For local development:

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

## Usage

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

```bash
gpufree
```

Check selected hosts:

```bash
gpufree 4090 L40
```

Filter default host discovery:

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

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

```bash
export GPUFREE_EXCLUDE=3090
```

Use JSON for scripts:

```bash
gpufree --json
```

## Shell Completion

For zsh:

```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:

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

Restart zsh or run:

```zsh
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

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

Build artifacts are written under `dist/`.
