0
# gpustat
1

2
A utility for monitoring NVIDIA GPU status and usage, providing a more concise and user-friendly alternative to nvidia-smi. It displays essential GPU information including temperature, utilization, memory usage, and running processes with their owners and memory consumption.
3

4
## Package Information
5

6
- **Package Name**: gpustat
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install gpustat`
10

11
## Core Imports
12

13
```python
14
import gpustat
15
```
16

17
Common usage patterns:
18

19
```python
20
from gpustat import new_query, print_gpustat, main
21
from gpustat import GPUStat, GPUStatCollection
22
from gpustat import __version__
23
```
24

25
## Basic Usage
26

27
```python
28
import gpustat
29

30
# Query all GPUs and get collection
31
gpu_stats = gpustat.new_query()
32

33
# Print formatted output to stdout
34
gpustat.print_gpustat()
35

36
# Get GPU count
37
count = gpustat.gpu_count()
38
print(f"Found {count} GPUs")
39

40
# Check if GPUs are available
41
if gpustat.is_available():
42
    print("NVIDIA GPUs are available")
43

44
# Access individual GPU information
45
for gpu in gpu_stats:
46
    print(f"GPU {gpu.index}: {gpu.name}")
47
    print(f"  Memory: {gpu.memory_used}MB / {gpu.memory_total}MB")
48
    print(f"  Temperature: {gpu.temperature}°C")
49
    print(f"  Utilization: {gpu.utilization}%")
50
```
51

52
## Capabilities
53

54
### GPU Query Functions
55

56
Query system GPU information and check availability.
57

58
```python { .api }
59
def new_query() -> GPUStatCollection:
60
    """
61
    Obtain a new GPUStatCollection instance by querying nvidia-smi
62
    to get the list of GPUs and running process information.
63
    
64
    Returns:
65
        GPUStatCollection: Collection of GPU status objects
66
    """
67

68
def gpu_count() -> int:
69
    """
70
    Return the number of available GPUs in the system.
71
    
72
    Returns:
73
        int: Number of GPUs available
74
    """
75

76
def is_available() -> bool:
77
    """
78
    Return True if the NVML library and GPU devices are available.
79
    
80
    Returns:
81
        bool: True if GPUs are available, False otherwise
82
    """
83
```
84

85
### Display Functions
86

87
Print GPU information in various formats.
88

89
```python { .api }
90
def print_gpustat(
91
    *,
92
    id=None,
93
    json=False,
94
    debug=False,
95
    **kwargs
96
) -> None:
97
    """
98
    Display the GPU query results into standard output.
99
    
100
    Parameters:
101
        id: Target specific GPU index or comma-separated indices
102
        json (bool): Print information in JSON format
103
        debug (bool): Print additional debug information
104
        **kwargs: Additional formatting options passed to print_formatted
105
    """
106

107
def main(*argv) -> None:
108
    """
109
    Main command-line interface entry point.
110
    
111
    Parameters:
112
        *argv: Command line arguments (defaults to sys.argv)
113
    """
114
115
```
116

117
### GPU Status Classes
118

119
Individual GPU status representation and collections.
120

121
```python { .api }
122
class GPUStat:
123
    """
124
    Represents status information for a single GPU.
125
    """
126
    
127
    def __init__(self, entry: dict) -> None:
128
        """
129
        Initialize GPU status from entry dictionary.
130
        
131
        Parameters:
132
            entry (dict): GPU information dictionary
133
        """
134
    
135
    @property
136
    def available(self) -> bool:
137
        """GPU availability status."""
138
    
139
    @property
140
    def index(self) -> int:
141
        """GPU index as in nvidia-smi."""
142
    
143
    @property
144
    def uuid(self) -> str:
145
        """GPU UUID from nvidia-smi (e.g. GPU-12345678-abcd-abcd-uuid-123456abcdef)."""
146
    
147
    @property
148
    def name(self) -> str:
149
        """GPU card name (e.g. GeForce Titan X)."""
150
    
151
    @property
152
    def memory_total(self) -> int:
153
        """Total memory in MB as integer."""
154
    
155
    @property
156
    def memory_used(self) -> int:
157
        """Occupied memory in MB as integer."""
158
    
159
    @property
160
    def memory_free(self) -> int:
161
        """Free (available) memory in MB as integer."""
162
    
163
    @property
164
    def memory_available(self) -> int:
165
        """Available memory in MB as integer (alias of memory_free)."""
166
    
167
    @property
168
    def temperature(self) -> int | None:
169
        """GPU temperature in Celsius, or None if not available."""
170
    
171
    @property
172
    def fan_speed(self) -> int | None:
173
        """Fan speed percentage (0-100), or None if not available."""
174
    
175
    @property
176
    def utilization(self) -> int | None:
177
        """GPU utilization percentage, or None if not available."""
178
    
179
    @property
180
    def utilization_enc(self) -> int | None:
181
        """GPU encoder utilization percentage, or None if not available."""
182
    
183
    @property
184
    def utilization_dec(self) -> int | None:
185
        """GPU decoder utilization percentage, or None if not available."""
186
    
187
    @property
188
    def power_draw(self) -> int | None:
189
        """GPU power usage in Watts, or None if not available."""
190
    
191
    @property
192
    def power_limit(self) -> int | None:
193
        """Enforced GPU power limit in Watts, or None if not available."""
194
    
195
    @property
196
    def processes(self) -> list:
197
        """List of running processes on the GPU."""
198
    
199
    def print_to(
200
        self,
201
        fp,
202
        *,
203
        with_colors: bool = True,
204
        show_cmd: bool = False,
205
        show_full_cmd: bool = False,
206
        no_processes: bool = False,
207
        show_user: bool = False,
208
        show_pid: bool = False,
209
        show_fan_speed: bool | None = None,
210
        show_codec: str = "",
211
        show_power: bool | None = None,
212
        gpuname_width: int | None = None,
213
        eol_char: str = os.linesep,
214
        term=None
215
    ) -> object:
216
        """
217
        Print formatted GPU information to file pointer.
218
        
219
        Parameters:
220
            fp: File pointer to write to
221
            with_colors (bool): Enable colored output (deprecated)
222
            show_cmd (bool): Display command name of running processes
223
            show_full_cmd (bool): Display full command and CPU stats
224
            no_processes (bool): Do not display process information
225
            show_user (bool): Display username of running processes
226
            show_pid (bool): Display PID of running processes
227
            show_fan_speed (bool): Display GPU fan speed
228
            show_codec (str): Show encoder/decoder utilization ("enc", "dec", "enc,dec")
229
            show_power (bool): Show GPU power usage
230
            gpuname_width (int): Width for GPU name display
231
            eol_char (str): End of line character
232
            term: Terminal object for formatting
233
            
234
        Returns:
235
            File pointer object
236
        """
237
    
238
    def jsonify(self) -> dict:
239
        """
240
        Convert GPU status to JSON-serializable dictionary.
241
        
242
        Returns:
243
            dict: JSON-serializable GPU information
244
        """
245

246

247
class GPUStatCollection:
248
    """
249
    Collection of GPU status objects with system information.
250
    Implements Sequence[GPUStat] interface.
251
    """
252
    
253
    def __init__(self, gpu_list: list, driver_version: str | None = None) -> None:
254
        """
255
        Initialize GPU collection.
256
        
257
        Parameters:
258
            gpu_list (list): List of GPUStat objects
259
            driver_version (str): NVIDIA driver version
260
        """
261
    
262
    @staticmethod
263
    def new_query(debug: bool = False, id=None) -> 'GPUStatCollection':
264
        """
265
        Query the information of all GPUs on local machine.
266
        
267
        Parameters:
268
            debug (bool): Enable debug output
269
            id: Target specific GPU index/indices (int, str, or Sequence)
270
            
271
        Returns:
272
            GPUStatCollection: New collection with current GPU status
273
        """
274
    
275
    @staticmethod
276
    def clean_processes() -> None:
277
        """Clean up cached process information for non-existent PIDs."""
278
    
279
    def __len__(self) -> int:
280
        """Return number of GPUs in collection."""
281
    
282
    def __iter__(self):
283
        """Iterate over GPU status objects."""
284
    
285
    def __getitem__(self, index: int) -> GPUStat:
286
        """Get GPU status by index."""
287
    
288
    def print_formatted(
289
        self,
290
        fp=sys.stdout,
291
        *,
292
        force_color: bool = False,
293
        no_color: bool = False,
294
        show_cmd: bool = False,
295
        show_full_cmd: bool = False,
296
        show_user: bool = False,
297
        show_pid: bool = False,
298
        show_fan_speed: bool | None = None,
299
        show_codec: str = "",
300
        show_power: bool | None = None,
301
        gpuname_width: int | None = None,
302
        show_header: bool = True,
303
        no_processes: bool = False,
304
        eol_char: str = os.linesep
305
    ) -> None:
306
        """
307
        Print formatted GPU information with various display options.
308
        
309
        Parameters:
310
            fp: File pointer to write to (default: sys.stdout)
311
            force_color (bool): Force colored output
312
            no_color (bool): Suppress colored output
313
            show_cmd (bool): Display command names of processes
314
            show_full_cmd (bool): Display full command and CPU stats
315
            show_user (bool): Display usernames of processes
316
            show_pid (bool): Display PIDs of processes
317
            show_fan_speed (bool): Display GPU fan speeds
318
            show_codec (str): Show encoder/decoder utilization
319
            show_power (bool): Show GPU power usage
320
            gpuname_width (int): Width for GPU name display
321
            show_header (bool): Show header with hostname and timestamp
322
            no_processes (bool): Hide process information
323
            eol_char (str): End of line character
324
        """
325
    
326
    def jsonify(self) -> dict:
327
        """
328
        Convert collection to JSON-serializable dictionary.
329
        
330
        Returns:
331
            dict: Complete system and GPU information
332
        """
333
    
334
    def print_json(self, fp=sys.stdout) -> None:
335
        """
336
        Print JSON representation to file pointer.
337
        
338
        Parameters:
339
            fp: File pointer to write to (default: sys.stdout)
340
        """
341
    
342
    @property
343
    def hostname(self) -> str:
344
        """System hostname."""
345
    
346
    @property
347
    def query_time(self) -> datetime:
348
        """Timestamp when query was performed."""
349
    
350
    @property
351
    def driver_version(self) -> str | None:
352
        """NVIDIA driver version string."""
353
```
354

355

356
### Internal Classes
357

358
Error handling and internal implementation classes.
359

360
```python { .api }
361
class InvalidGPU(GPUStat):
362
    """
363
    Internal class representing a GPU that encountered an error during querying.
364
    Inherits from GPUStat but returns fallback values for most properties.
365
    Not part of public API but may appear in collections during error conditions.
366
    """
367
    
368
    class FallbackDict(dict):
369
        """Internal dictionary that returns '?' for missing keys."""
370
        def __missing__(self, key: str) -> str:
371
            return "?"
372
    
373
    def __init__(self, gpu_index: int, message: str, ex: Exception) -> None:
374
        """
375
        Initialize invalid GPU with error information.
376
        
377
        Parameters:
378
            gpu_index (int): GPU index that failed
379
            message (str): Error message  
380
            ex (Exception): Original exception that caused the failure
381
        """
382
    
383
    @property
384
    def available(self) -> bool:
385
        """Always returns False for invalid GPUs."""
386
    
387
    @property  
388
    def exception(self) -> Exception:
389
        """Original exception that caused GPU to be invalid."""
390
```
391

392
## Types
393

394
```python { .api }
395
from typing import Sequence
396
from datetime import datetime
397
import os
398
import sys
399

400
# Process information dictionary structure
401
ProcessInfo = dict[str, any]  # Contains: username, command, full_command, 
402
                             # gpu_memory_usage, cpu_percent, cpu_memory_usage, pid
403

404
# GPU entry dictionary structure  
405
GPUEntry = dict[str, any]  # Contains: index, uuid, name, temperature.gpu,
406
                          # fan.speed, utilization.gpu, utilization.enc,
407
                          # utilization.dec, power.draw, enforced.power.limit,
408
                          # memory.used, memory.total, processes
409

410
# Exception types used in error handling
411
NVMLError = Exception  # NVIDIA Management Library errors
412
AccessDenied = Exception  # Process access denied errors  
413
NoSuchProcess = Exception  # Process no longer exists errors
414
415
```
416

417
## Constants
418

419
```python { .api }
420
__version__: str  # Package version string
421
NOT_SUPPORTED: str = 'Not Supported'
422
MB: int = 1024 * 1024  # Bytes to MB conversion factor
423
DEFAULT_GPUNAME_WIDTH: int = 16
424
IS_WINDOWS: bool  # True if running on Windows platform
425
```
426

427
## Command Line Interface
428

429
The package provides a command-line interface accessible via:
430

431
- `gpustat` command (installed via entry point)
432
- `python -m gpustat` (via __main__ module)
433

434
### Common CLI Options
435

436
```bash
437
# Basic usage
438
gpustat
439

440
# JSON output
441
gpustat --json
442

443
# Watch mode (update every 2 seconds)  
444
gpustat --interval 2
445

446
# Show all information
447
gpustat --show-all
448

449
# Show specific information
450
gpustat --show-cmd --show-user --show-pid --show-fan-speed --show-power
451

452
# Target specific GPUs
453
gpustat --id 0,1
454

455
# Colored output
456
gpustat --force-color
457

458
# No processes
459
gpustat --no-processes
460

461
# No header
462
gpustat --no-header
463

464
# Custom GPU name width
465
gpustat --gpuname-width 20
466

467
# Debug mode
468
gpustat --debug
469

470
# Show encoder/decoder utilization
471
gpustat --show-codec enc,dec
472

473
# Show power usage with limits
474
gpustat --show-power draw,limit
475
```
476

477
## Error Handling
478

479
The library handles various NVIDIA driver and hardware error conditions:
480

481
- **NVML library unavailable**: Returns empty results or raises ImportError
482
- **GPU lost or unknown errors**: Creates InvalidGPU objects with error details  
483
- **Process access denied**: Skips inaccessible process information
484
- **Driver compatibility issues**: Provides fallback API calls and warnings
485
- **Missing GPU features**: Returns None for unsupported properties (temperature, fan speed, etc.)
486

487
## Dependencies
488

489
- **nvidia-ml-py>=11.450.129**: NVIDIA Management Library Python bindings
490
- **psutil>=5.6.0**: System and process utilities
491
- **blessed>=1.17.1**: Terminal formatting and colors