Metadata-Version: 2.4
Name: ntop
Version: 0.1.0
Summary: An interactive Ascend NPU / NVIDIA GPU process viewer, supporting both DCMI and NVML backends.
Author: Byter
License: Apache-2.0 AND GPL-3.0-only
Project-URL: Homepage, https://github.com/Byter-s/ntop
Project-URL: Repository, https://github.com/Byter-s/ntop
Project-URL: Changelog, https://github.com/Byter-s/ntop/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Byter-s/ntop/issues
Keywords: ascend,npu,huawei,dcmi,nvidia,GPU,top,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: GPU
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COPYING
Requires-Dist: nvidia-ml-py>=11.450.51
Requires-Dist: psutil>=5.6.6
Requires-Dist: colorama>=0.4.0; platform_system == "Windows"
Requires-Dist: windows-curses>=2.2.0; platform_system == "Windows"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: ruff; extra == "test"
Dynamic: license-file

# ntop

[![Python](https://img.shields.io/pypi/pyversions/ntop)](https://pypi.org/project/ntop/)
[![PyPI](https://img.shields.io/pypi/v/ntop)](https://pypi.org/project/ntop/)
[![License](https://img.shields.io/badge/license-Apache--2.0%20AND%20GPL--3.0--only-blue)](#license)

`ntop` is an interactive **Huawei Ascend NPU and NVIDIA GPU process monitor** for
the terminal. It adds a native DCMI backend for Ascend devices while retaining
the mature NVML monitoring experience inherited from
[`nvitop`](https://github.com/XuehaiPan/nvitop).

The name means **NPU top**. The command automatically selects Ascend when DCMI
reports at least one NPU and otherwise falls back to NVIDIA/NVML.

## Features

- Monitor Ascend NPU HBM usage, AICore utilization, temperature, power, clocks,
  PCIe address, and device processes through `libdcmi.so`.
- Monitor NVIDIA GPUs through NVML, including the features provided by the
  upstream `nvitop` codebase.
- Use an interactive curses interface with full, compact, and automatic layouts.
- Sort and filter processes, inspect process metrics and environments, use tree
  view, and send signals from the TUI.
- Print a colorized one-shot status report for scripts and SSH sessions.
- Inspect backend and system diagnostics with `ntop env`.
- Choose a backend explicitly when both drivers are installed.

## Installation

`ntop` requires Python 3.8 or newer.

```bash
python -m pip install --upgrade ntop
```

An isolated command-line installation is also supported:

```bash
pipx install ntop
# or run without a persistent installation
uvx ntop
```

To install the current checkout for development:

```bash
git clone https://github.com/Byter-s/ntop.git
cd ntop
python -m pip install -e .
```

The Python dependencies are intentionally broad: `psutil>=5.6.6` and
`nvidia-ml-py>=11.450.51`, with no upper bounds. `nvidia-ml-py` is a pure-Python
binding and can be installed on Ascend-only hosts; an NVIDIA driver is not
required unless the NVIDIA backend is used.

### Hardware backends

| Backend | Runtime requirement | Notes |
| --- | --- | --- |
| Ascend | Huawei Ascend driver and `libdcmi.so` | Linux only; selected first in auto mode when an NPU is reported |
| NVIDIA | NVIDIA driver with NVML | Used when Ascend is unavailable or `--backend nvidia` is given |

On Linux, `curses` is part of Python. On Windows, `windows-curses` and
`colorama` are installed automatically. The Ascend backend itself is Linux-only.

## Quick start

Interactive monitor:

```bash
ntop
ntop --backend ascend
ntop --backend nvidia -m full
ntop -m compact --interval 1
```

One-shot report:

```bash
ntop -1
ntop -1 -o 0 1
ntop -1 --only-visible
```

Environment and driver diagnostics:

```bash
ntop env
ntop --backend ascend env
```

If another program named `ntop` is earlier on your `PATH`, the equivalent module
entry point is always available:

```bash
python -m ntop
```

## Common options

```text
--backend {auto,ascend,nvidia}  Choose the device backend (default: auto)
-1, --once                     Print one report and exit
-m, --monitor [MODE]           Monitor continuously (auto, full, or compact)
--interval SEC                 Refresh interval
-o, --only INDEX [...]         Show only selected physical device indices
-ov, --only-visible            Respect the selected backend's visibility variable
-u, --user [USERNAME ...]      Filter by user; no username means current user
-p, --pid PID [...]            Filter by PID
-c, --compute                  Show compute processes
-U, --ascii                    Use ASCII characters only
--colorful                     Enable 256-color bar charts
--light                        Adjust colors for a light terminal
--profile [FILE]               Write refresh timings to CSV
```

Run `ntop --help` for the complete and authoritative option list.

## Backend selection and environment variables

| Variable | Description | Default |
| --- | --- | --- |
| `NTOP_BACKEND` | `auto`, `ascend`, or `nvidia` | `auto` |
| `NTOP_DCMI_LIBRARY` | Explicit path or loader name for `libdcmi.so` | auto-discovered |
| `NTOP_MONITOR_MODE` | Comma-separated mode/theme settings such as `full,colorful,dark` | `auto,plain,dark` |
| `NTOP_GPU_UTILIZATION_THRESHOLDS` | Utilization color thresholds, for example `10,75` | `10,75` |
| `NTOP_MEMORY_UTILIZATION_THRESHOLDS` | Memory color thresholds, for example `10,80` | `10,80` |
| `NPU_VISIBLE_DEVICES` | Visible Ascend logical indices | all |
| `ASCEND_VISIBLE_DEVICES` | Fallback Ascend visibility variable | all |
| `CUDA_VISIBLE_DEVICES` | Visible NVIDIA devices | all |

For compatibility with inherited configurations, the legacy
`NVITOP_MONITOR_MODE`, `NVITOP_GPU_UTILIZATION_THRESHOLDS`, and
`NVITOP_MEMORY_UTILIZATION_THRESHOLDS` variables are also accepted when the
corresponding `NTOP_*` variable is unset.

DCMI discovery checks `NTOP_DCMI_LIBRARY`, the system dynamic linker, and these
common paths:

```text
/usr/local/Ascend/driver/lib64/driver/libdcmi.so
/usr/local/Ascend/driver/lib64/common/libdcmi.so
/usr/local/dcmi/lib64/libdcmi.so
```

## Keybindings

| Key | Action |
| --- | --- |
| `q` | Quit or return |
| `h` / `?` | Open help |
| `a` / `f` / `c` | Switch to auto / full / compact mode |
| `r` / `Ctrl-R` / `F5` | Refresh |
| Arrow keys / mouse wheel | Select a process |
| `Space` | Tag or untag a process |
| `Ctrl-C` / `I`, `T`, `K` | Interrupt, terminate, or kill selected processes |
| `e` | Show the selected process environment |
| `t` | Toggle process tree view |
| `Enter` | Open process metrics |
| `,` / `.` | Select the sort column |
| `/` | Reverse sort order |

## Python API

The NVIDIA-compatible API remains available, with explicit Ascend classes added:

```python
from ntop import AscendDevice, Device

# Ascend
ascend_devices = AscendDevice.all()

# NVIDIA
nvidia_devices = Device.all()
```

The command-line backend selection does not change what `Device` means in Python:
`Device` is the upstream NVIDIA/NVML class, while `AscendDevice` is the DCMI
class.

## Ascend notes

- DCMI support varies across driver and firmware releases. Metrics that the
  installed DCMI does not expose are displayed as `N/A` rather than guessed.
- Per-process HBM usage is available. Per-process AICore/HBM-bandwidth
  utilization may remain `N/A` because the DCMI resource API does not provide it.
- In containers, mount the Ascend driver libraries and device nodes as required
  by your runtime. `ntop env` is the fastest way to diagnose discovery failures.

## License

This is a derivative of `nvitop` and preserves its dual-license layout:

- API code: Apache License 2.0 — see [`LICENSE`](LICENSE).
- CLI and TUI code: GNU GPL version 3 — see [`COPYING`](COPYING).

The distribution license expression is `Apache-2.0 AND GPL-3.0-only`. Original
copyright and license notices are retained in derived source files.

## Acknowledgements

`ntop` is built from [`nvitop`](https://github.com/XuehaiPan/nvitop) by
[Xuehai Pan](https://github.com/XuehaiPan). Its NVML API wrappers, host process
monitoring, and curses interface form the foundation of this project. Thanks to
the upstream authors and contributors for their work.
