nvitop.process module

HostProcess([pid])

Represent an OS process with the given PID.

GpuProcess(pid, device, *[, gpu_memory, ...])

Represent a process with the given PID running on the given GPU device.

command_join(cmdline)

Return a shell-escaped string from a list of command line arguments.

The live classes for processes running on the host and the GPU devices.

class nvitop.HostProcess(pid: int | None = None)[source]

Bases: Process, ABC

Represent an OS process with the given PID.

If PID is omitted, the current process PID (os.getpid()) is used. The instance will be cached during the lifetime of the process.

Examples

>>> HostProcess()  # the current process
HostProcess(pid=12345, name='python3', status='running', started='00:55:43')

>>> p1 = HostProcess(12345)
>>> p2 = HostProcess(12345)
>>> p1 is p2                 # the same instance
True

>>> import copy
>>> copy.deepcopy(p1) is p1  # the same instance
True

>>> p = HostProcess(pid=12345)
>>> p.cmdline()
['python3', '-c', 'import IPython; IPython.terminal.ipapp.launch_new_instance()']
>>> p.command()  # the result is in shell-escaped format
'python3 -c "import IPython; IPython.terminal.ipapp.launch_new_instance()"'

>>> p.as_snapshot()
HostProcessSnapshot(
    real=HostProcess(pid=12345, name='python3', status='running', started='00:55:43'),
    cmdline=['python3', '-c', 'import IPython; IPython.terminal.ipapp.launch_new_instance()'],
    command='python3 -c "import IPython; IPython.terminal.ipapp.launch_new_instance()"',
    connections=[],
    cpu_percent=0.3,
    cpu_times=pcputimes(user=2.180019456, system=0.18424464, children_user=0.0, children_system=0.0),
    create_time=1656608143.31,
    cwd='/home/panxuehai',
    environ={...},
    ...
)
INSTANCE_LOCK: RLock = <unlocked _thread.RLock object owner=0 count=0>
INSTANCES: WeakValueDictionary[int, HostProcess] = <WeakValueDictionary>
static __new__(cls, pid: int | None = None) → Self[source]

Return the cached instance of HostProcess.

__init__(pid: int | None = None) → None[source]

Initialize the instance.

__repr__() → str[source]

Return a string representation of the process.

__reduce__() → tuple[type[HostProcess], tuple[int]][source]

Return state information for pickling.

username() → str[source]

Return the name of the user that owns the process.

On UNIX this is calculated by using real process uid.

Raises:
cmdline() → list[str][source]

Return the command line this process has been called with.

Raises:
command() → str[source]

Return a shell-escaped string from command line arguments.

Raises:
running_time() → timedelta[source]

Return the elapsed time this process has been running as a datetime.timedelta.

Raises:
running_time_human() → str[source]

Return the elapsed time this process has been running in human-readable format.

Raises:
running_time_in_seconds() → float[source]

Return the elapsed time this process has been running in seconds.

Raises:
elapsed_time() → timedelta

Return the elapsed time this process has been running as a datetime.timedelta.

Raises:
elapsed_time_human() → str

Return the elapsed time this process has been running in human-readable format.

Raises:
elapsed_time_in_seconds() → float

Return the elapsed time this process has been running in seconds.

Raises:
rss_memory() → int[source]

Return the used resident set size (RSS) memory of the process in bytes.

Raises:
parent() → HostProcess | None[source]

Return the parent process as a HostProcess instance or None if there is no parent.

Raises:
children(recursive: bool = False) → list[HostProcess][source]

Return the children of this process as a list of HostProcess instances.

If recursive is True return all the descendants.

Raises:
oneshot() → Generator[None][source]

A utility context manager which considerably speeds up the retrieval of multiple process information at the same time.

Internally different process info (e.g. name, ppid, uids, gids, …) may be fetched by using the same routine, but only one information is returned and the others are discarded. When using this context manager the internal routine is executed once (in the example below on name()) and the other info are cached.

The cache is cleared when exiting the context manager block. The advice is to use this every time you retrieve more than one information about the process.

Examples

>>> from nvitop import HostProcess
>>> p = HostProcess()
>>> with p.oneshot():
...     p.name()         # collect multiple info
...     p.cpu_times()    # return cached value
...     p.cpu_percent()  # return cached value
...     p.create_time()  # return cached value
as_snapshot(attrs: Iterable[str] | None = None, ad_value: Any | None = None) → Snapshot[source]

Return a one-time snapshot of the process.

as_dict(attrs=None, ad_value=None)

Utility method returning process information as a hashable dictionary. If attrs is specified it must be a list of strings reflecting available Process class’ attribute names (e.g. [‘cpu_times’, ‘name’]) else all public (read only) attributes are assumed. ad_value is the value which gets assigned in case AccessDenied or ZombieProcess exception is raised when retrieving that particular process information.

connections(kind='inet')

connections() is deprecated and will be removed; use net_connections() instead

cpu_affinity(cpus=None)

Get or set process CPU affinity. If specified, cpus must be a list of CPUs for which you want to set the affinity (e.g. [0, 1]). If an empty list is passed, all egible CPUs are assumed (and set). (Windows, Linux and BSD only).

cpu_num()

Return what CPU this process is currently running on. The returned number should be <= psutil.cpu_count() and <= len(psutil.cpu_percent(percpu=True)). It may be used in conjunction with psutil.cpu_percent(percpu=True) to observe the system workload distributed across CPUs.

cpu_percent(interval=None)

Return a float representing the current process CPU utilization as a percentage.

When interval is 0.0 or None (default) compares process times to system CPU times elapsed since last call, returning immediately (non-blocking). That means that the first time this is called it will return a meaningful 0.0 value.

When interval is > 0.0 compares process times to system CPU times elapsed before and after the interval (blocking).

In this case is recommended for accuracy that this function be called with at least 0.1 seconds between calls.

A value > 100.0 can be returned in case of processes running multiple threads on different CPU cores.

The returned value is explicitly NOT split evenly between all available logical CPUs. This means that a busy loop process running on a system with 2 logical CPUs will be reported as having 100% CPU utilization instead of 50%.

Examples

>>> import psutil
>>> p = psutil.Process(os.getpid())
>>> # blocking
>>> p.cpu_percent(interval=1)
2.0
>>> # non-blocking (percentage since last call)
>>> p.cpu_percent(interval=None)
2.9
>>>
cpu_times()

Return a (user, system, children_user, children_system) namedtuple representing the accumulated process time, in seconds. This is similar to os.times() but per-process. On macOS and Windows children_user and children_system are always set to 0.

create_time()

The process creation time as a floating point number expressed in seconds since the epoch (seconds since January 1, 1970, at midnight UTC). The return value, which is cached after first call, is based on the system clock, which means it may be affected by changes such as manual adjustments or time synchronization (e.g. NTP).

cwd()

Process current working directory as an absolute path.

environ()

The environment variables of the process as a dict. Note: this might not reflect changes made after the process started.

exe()

The process executable as an absolute path. May also be an empty string. The return value is cached after first call.

gids()

Return process GIDs as a (real, effective, saved) namedtuple.

io_counters()

Return process I/O statistics as a (read_count, write_count, read_bytes, write_bytes) namedtuple. Those are the number of read/write calls performed and the amount of bytes read and written by the process.

ionice(ioclass=None, value=None)

Get or set process I/O niceness (priority).

On Linux ioclass is one of the IOPRIO_CLASS_* constants. value is a number which goes from 0 to 7. The higher the value, the lower the I/O priority of the process.

On Windows only ioclass is used and it can be set to 2 (normal), 1 (low) or 0 (very low).

Available on Linux and Windows > Vista only.

is_running()

Return whether this process is running.

It also checks if PID has been reused by another process, in which case it will remove the process from process_iter() internal cache and return False.

kill()

Kill the current process with SIGKILL pre-emptively checking whether PID has been reused.

memory_full_info()

This method returns the same information as memory_info(), plus, on some platform (Linux, macOS, Windows), also provides additional metrics (USS, PSS and swap). The additional metrics provide a better representation of actual process memory usage.

Namely USS is the memory which is unique to a process and which would be freed if the process was terminated right now.

It does so by passing through the whole process address. As such it usually requires higher user privileges than memory_info() and is considerably slower.

memory_info()

Return a namedtuple with variable fields depending on the platform, representing memory information about the process.

The “portable” fields available on all platforms are rss and vms.

All numbers are expressed in bytes.

memory_maps(grouped=True)

Return process’ mapped memory regions as a list of namedtuples whose fields are variable depending on the platform.

If grouped is True the mapped regions with the same ‘path’ are grouped together and the different memory fields are summed.

If grouped is False every mapped region is shown as a single entity and the namedtuple will also include the mapped region’s address space (‘addr’) and permission set (‘perms’).

memory_percent(memtype='rss')

Compare process memory to total physical system memory and calculate process memory utilization as a percentage. memtype argument is a string that dictates what type of process memory you want to compare against (defaults to “rss”). The list of available strings can be obtained like this:

>>> psutil.Process().memory_info()._fields
('rss', 'vms', 'shared', 'text', 'lib', 'data', 'dirty', 'uss', 'pss')
name()

The process name. The return value is cached after first call.

net_connections(kind='inet')

Return socket connections opened by process as a list of (fd, family, type, laddr, raddr, status) namedtuples. The kind parameter filters for connections that match the following criteria:

Kind Value

Connections using

inet inet4 inet6 tcp tcp4 tcp6 udp udp4 udp6 unix all

IPv4 and IPv6 IPv4 IPv6 TCP TCP over IPv4 TCP over IPv6 UDP UDP over IPv4 UDP over IPv6 UNIX socket (both UDP and TCP protocols) the sum of all the possible families and protocols
nice(value=None)

Get or set process niceness (priority).

num_ctx_switches()

Return the number of voluntary and involuntary context switches performed by this process.

num_fds()

Return the number of file descriptors opened by this process (POSIX only).

num_threads()

Return the number of threads used by this process.

open_files()

Return files opened by process as a list of (path, fd) namedtuples including the absolute file name and file descriptor number.

parents()

Return the parents of this process as a list of Process instances. If no parents are known return an empty list.

property pid

The process PID.

ppid()

The process parent PID. On Windows the return value is cached after first call.

resume()

Resume process execution with SIGCONT pre-emptively checking whether PID has been reused. On Windows this has the effect of resuming all process threads.

rlimit(resource, limits=None)

Get or set process resource limits as a (soft, hard) tuple.

resource is one of the RLIMIT_* constants. limits is supposed to be a (soft, hard) tuple.

See “man prlimit” for further info. Available on Linux and FreeBSD only.

send_signal(sig)

Send a signal sig to process pre-emptively checking whether PID has been reused (see signal module constants) . On Windows only SIGTERM is valid and is treated as an alias for kill().

status()

The process current status as a STATUS_* constant.

suspend()

Suspend process execution with SIGSTOP pre-emptively checking whether PID has been reused. On Windows this has the effect of suspending all process threads.

terminal()

The terminal associated with this process, if any, else None.

terminate()

Terminate the process with SIGTERM pre-emptively checking whether PID has been reused. On Windows this is an alias for kill().

threads()

Return threads opened by process as a list of (id, user_time, system_time) namedtuples representing thread id and thread CPU times (user/system). On OpenBSD this method requires root access.

uids()

Return process UIDs as a (real, effective, saved) namedtuple.

wait(timeout=None)

Wait for process to terminate, and if process is a children of os.getpid(), also return its exit code, else None. On Windows there’s no such limitation (exit code is always returned).

If the process is already terminated, immediately return None instead of raising NoSuchProcess.

If timeout (in seconds) is specified and process is still alive, raise TimeoutExpired.

If timeout=0 either return immediately or raise TimeoutExpired (non-blocking).

To wait for multiple Process objects use psutil.wait_procs().

class nvitop.GpuProcess(pid: int | None, device: Device, *, gpu_memory: int | NaType | None = None, gpu_instance_id: int | NaType | None = None, compute_instance_id: int | NaType | None = None, type: str | NaType | None = None)[source]

Bases: object

Represent a process with the given PID running on the given GPU device.

The instance will be cached during the lifetime of the process.

The same host process can use multiple GPU devices. The GpuProcess instances representing the same PID on the host but different GPU devices are different.

INSTANCE_LOCK: threading.RLock = <unlocked _thread.RLock object owner=0 count=0>
INSTANCES: WeakValueDictionary[tuple[int, Device], GpuProcess] = <WeakValueDictionary>
static __new__(cls, pid: int | None, device: Device, *, gpu_memory: int | NaType | None = None, gpu_instance_id: int | NaType | None = None, compute_instance_id: int | NaType | None = None, type: str | NaType | None = None) → Self[source]

Return the cached instance of GpuProcess.

__init__(pid: int | None, device: Device, *, gpu_memory: int | NaType | None = None, gpu_instance_id: int | NaType | None = None, compute_instance_id: int | NaType | None = None, type: str | NaType | None = None) → None[source]

Initialize the instance returned by __new__().

__repr__() → str[source]

Return a string representation of the GPU process.

__eq__(other: object) → bool[source]

Test equality to other object.

__hash__() → int[source]

Return a hash value of the GPU process.

__getattr__(name: str) → Any | Callable[..., Any][source]

Get a member from the instance or fallback to the host process instance if missing.

Raises:
property pid: int

The process PID.

property host: HostProcess

The process instance running on the host.

property device: Device

The GPU device the process running on.

The same host process can use multiple GPU devices. The GpuProcess instances representing the same PID on the host but different GPU devices are different.

gpu_instance_id() → int | NaType[source]

Return the GPU instance ID of the MIG device, or nvitop.NA if not applicable.

compute_instance_id() → int | NaType[source]

Return the compute instance ID of the MIG device, or nvitop.NA if not applicable.

gpu_memory() → int | NaType[source]

Return the used GPU memory in bytes, or nvitop.NA if not applicable.

gpu_memory_human() → str | NaType[source]

Return the used GPU memory in human-readable format, or nvitop.NA if not applicable.

gpu_memory_percent() → float | NaType[source]

Return the percentage of used GPU memory by the process, or nvitop.NA if not applicable.

gpu_sm_utilization() → int | NaType[source]

Return the utilization rate of SM (Streaming Multiprocessor), or nvitop.NA if not applicable.

gpu_memory_utilization() → int | NaType[source]

Return the utilization rate of GPU memory bandwidth, or nvitop.NA if not applicable.

gpu_encoder_utilization() → int | NaType[source]

Return the utilization rate of the encoder, or nvitop.NA if not applicable.

gpu_decoder_utilization() → int | NaType[source]

Return the utilization rate of the decoder, or nvitop.NA if not applicable.

set_gpu_memory(value: int | NaType) → None[source]

Set the used GPU memory in bytes.

set_gpu_utilization(gpu_sm_utilization: int | NaType | None = None, gpu_memory_utilization: int | NaType | None = None, gpu_encoder_utilization: int | NaType | None = None, gpu_decoder_utilization: int | NaType | None = None) → None[source]

Set the GPU utilization rates.

update_gpu_status() → int | NaType[source]

Update the GPU consumption status from a new NVML query.

property type: str | NaType

The type of the GPU context.

The type is one of the following:

  • 'C': compute context

  • 'G': graphics context

  • 'C+G': both compute context and graphics context

  • 'N/A': not applicable

is_running() → bool[source]

Return whether this process is running.

status() → str[source]

Return the process current status.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

create_time() → float | NaType[source]

Return the process creation time as a floating point number expressed in seconds since the epoch.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

running_time() → timedelta | NaType[source]

Return the elapsed time this process has been running as a datetime.timedelta.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

running_time_human() → str | NaType[source]

Return the elapsed time this process has been running in human-readable format.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

running_time_in_seconds() → float | NaType[source]

Return the elapsed time this process has been running in seconds.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

elapsed_time() → timedelta | NaType

Return the elapsed time this process has been running as a datetime.timedelta.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

elapsed_time_human() → str | NaType

Return the elapsed time this process has been running in human-readable format.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

elapsed_time_in_seconds() → float | NaType

Return the elapsed time this process has been running in seconds.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

username() → str | NaType[source]

Return the name of the user that owns the process.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

name() → str | NaType[source]

Return the process name.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

cpu_percent() → float | NaType[source]

Return a float representing the current process CPU utilization as a percentage.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

memory_percent() → float | NaType[source]

Compare process RSS memory to total physical system memory and calculate process memory utilization as a percentage.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

host_memory_percent() → float | NaType

Compare process RSS memory to total physical system memory and calculate process memory utilization as a percentage.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

host_memory() → int | NaType[source]

Return the used resident set size (RSS) memory of the process in bytes.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

host_memory_human() → str | NaType[source]

Return the used resident set size (RSS) memory of the process in human-readable format.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

rss_memory() → int | NaType

Return the used resident set size (RSS) memory of the process in bytes.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

cmdline() → list[str][source]

Return the command line this process has been called with.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

command() → str[source]

Return a shell-escaped string from command line arguments.

Raises:

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). See also take_snapshots() and failsafe().

host_snapshot() → Snapshot[source]

Return a one-time snapshot of the host process.

as_snapshot(*, host_process_snapshot_cache: dict[int, Snapshot] | None = None) → Snapshot[source]

Return a one-time snapshot of the process on the GPU device.

Note

To return the fallback value rather than raise an exception, please use the context manager GpuProcess.failsafe(). Also, consider using the batched version to take snapshots with GpuProcess.take_snapshots(), which caches the results and reduces redundant queries. See also take_snapshots() and failsafe().

classmethod take_snapshots(gpu_processes: Iterable[GpuProcess], *, failsafe: bool = False) → list[Snapshot][source]

Take snapshots for a list of GpuProcess instances.

If failsafe is True, then if any method fails, the fallback value in auto_garbage_clean() will be used.

classmethod failsafe() → Generator[None][source]

A context manager that enables fallback values for methods that fail.

Examples

>>> p = GpuProcess(pid=10000, device=Device(0))  # process does not exist
>>> p
GpuProcess(pid=10000, gpu_memory=N/A, type=N/A, device=PhysicalDevice(index=0, name="NVIDIA GeForce RTX 3070", total_memory=8192MiB), host=HostProcess(pid=10000, status='terminated'))
>>> p.cpu_percent()
Traceback (most recent call last):
    ...
NoSuchProcess: process no longer exists (pid=10000)

>>> # Failsafe to the fallback value instead of raising exceptions
... with GpuProcess.failsafe():
...     print('fallback:              {!r}'.format(p.cpu_percent()))
...     print('fallback (float cast): {!r}'.format(float(p.cpu_percent())))  # `nvitop.NA` can be cast to float or int
...     print('fallback (int cast):   {!r}'.format(int(p.cpu_percent())))    # `nvitop.NA` can be cast to float or int
fallback:              'N/A'
fallback (float cast): nan
fallback (int cast):   0
nvitop.command_join(cmdline: list[str]) → str[source]

Return a shell-escaped string from a list of command line arguments.