Metadata-Version: 2.4
Name: gpu-detector
Version: 1.0.0
Summary: Cross-platform GPU detection library
Author: sgaxr
License-Expression: MIT
Project-URL: Repository, https://github.com/sgaxr/gpu_detector
Project-URL: Issues, https://github.com/sgaxr/gpu_detector/issues
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: Operating System :: OS Independent
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# gpu-detector

Cross-platform GPU detection library for Python. Detects NVIDIA, AMD, Intel, Apple, and other GPUs on Linux, Windows, and macOS. Detects VRAM where the OS exposes it.

Most existing Python GPU detection tools are thin wrappers around `nvidia-smi` and only work for NVIDIA GPUs. **gpu-detector** was built to fill that gap: it detects *all* GPUs in a system, regardless of vendor, using the best available method on each platform.

## Usage

```python
from gpu_detector import detect, GPUInfo

gpus: list[GPUInfo] = detect()
for gpu in gpus:
    print(gpu)
```

Or from the command line:

```bash
gpu-detector
```

## `GPUInfo` dataclass

Each detected GPU is returned as a [`GPUInfo`](gpu_detector/models.py) instance with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `name` | `str` | GPU name as reported by the system (e.g. `"NVIDIA GeForce RTX 4090"`) |
| `vendor` | `str \| None` | Canonical vendor name: `"NVIDIA"`, `"AMD"`, `"Intel"`, `"Apple"`, `"Matrox"`, `"ASPEED"`, `"VIA"`, `"Moore Threads"`, `"Zhaoxin"`, `"VMware"`, `"Red Hat"`, `"QEMU/Bochs"`, or `"VirtualBox"` |
| `memory_mb` | `int \| None` | Dedicated VRAM in megabytes. Populated for all vendors where the OS exposes it; `None` for integrated GPUs with shared memory. |
| `driver_version` | `str \| None` | Driver version string, if available. |
| `device_id` | `str \| None` | PCI device ID (e.g. `"10de:2620"`), PNP device ID (Windows), or platform-specific identifier. |
| `source` | `str \| None` | Detection method that produced this entry (e.g. `"lspci:-nn"`, `"nvidia-smi"`, `"powershell:Get-CimInstance Win32_VideoController"`). |

### `__str__` output

```python
print(gpu)
# → "NVIDIA GeForce RTX 4090 (NVIDIA) 24576 MB"
```

## Supported vendors

### Physical GPUs

| Vendor | PCI IDs |
|--------|---------|
| NVIDIA | `0x10de` |
| AMD / ATI | `0x1002`, `0x1022` |
| Intel | `0x8086` |
| Apple | `0x106b` |
| Matrox | `0x102b` |
| ASPEED | `0x1a03` |
| VIA | `0x1106` |
| Moore Threads | `0x1ed5` |
| Zhaoxin | `0x1d17` |

### Virtual GPUs

| Vendor | PCI IDs |
|--------|---------|
| VMware SVGA | `0x15ad` |
| Red Hat virtio-gpu | `0x1af4` |
| QEMU / Bochs | `0x1234` |
| VirtualBox | `0x80ee` |

## Detection methods by platform

### Linux

1. **`lspci -nn`** — primary detection; identifies GPUs by PCI class.
2. **`/sys/class/drm`** — fallback when `lspci` is unavailable.
3. **`nvidia-smi`** — enriches NVIDIA entries with VRAM, driver version, and accurate names.
4. **DRM sysfs VRAM** — reads `/sys/class/drm/card*/device/mem_info_vram_total` for AMD (amdgpu) and Intel Arc (xe/i915) VRAM.

### Windows

1. **PowerShell** (`Get-CimInstance Win32_VideoController`) — primary; returns name, AdapterRAM, driver version, and PNP device ID for all vendors.
2. **WMIC** — fallback using the same WMI class.

### macOS

1. **`system_profiler -json`** — primary; returns model, VRAM, vendor, and device ID.
2. **`system_profiler`** (plain text) — fallback parsing of the text output.

## Contributing

Pull requests are welcome! Whether it's adding support for a new vendor, improving detection on a specific platform, or fixing a bug, contributions of all sizes are appreciated.

## Accuracy

This library is developed with limited access to operating systems and GPU hardware. Detection results may not be accurate for all configurations. If you encounter incorrect or missing information on your system, please [open an issue](https://github.com/sgaxr/gpu_detector/issues) with your GPU model, OS, and the output you received. It helps improve detection for everyone.
