Metadata-Version: 2.4
Name: ascend-nputop
Version: 0.0.2
Summary: An interactive Ascend-NPU process viewer.
Author: Lianzhong You
Author-email: Lianzhong You <youlianzhong@gml.ac.cn>
License: Apache License, Version 2.0 (Apache-2.0) & GNU General Public License, Version 3 (GPL-3.0)
Project-URL: Homepage, https://github.com/youyve/nputop
Project-URL: Repository, https://github.com/youyve/nputop
Project-URL: Documentation, https://nputop.readthedocs.io
Project-URL: Bug Report, https://github.com/youyve/nputop/issues
Keywords: ascend,npu-smi,Ascend,pyacl,NPU,top,monitoring
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
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.7
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COPYING
License-File: NOTICE
Requires-Dist: psutil>=5.6.6
Requires-Dist: cachetools>=1.0.1
Requires-Dist: termcolor>=1.0.0
Requires-Dist: colorama>=0.4.0; platform_system == "Windows"
Requires-Dist: windows-curses>=2.2.0; platform_system == "Windows"
Provides-Extra: lint
Requires-Dist: black<25.0.0a0,>=24.0.0; extra == "lint"
Requires-Dist: isort; extra == "lint"
Requires-Dist: pylint[spelling]; extra == "lint"
Requires-Dist: mypy; extra == "lint"
Requires-Dist: typing-extensions; extra == "lint"
Requires-Dist: pre-commit; extra == "lint"
Provides-Extra: cuda10
Requires-Dist: nvidia-ml-py==11.450.51; extra == "cuda10"
Dynamic: author
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-python

# nputop: Interactive Ascend-NPU Process Viewer 🚀

[![License](https://img.shields.io/badge/license-Apache%202.0%20%7C%20GPLv3-blue.svg)](LICENSE)
[![Python Versions](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://www.python.org/)
![Platform](https://img.shields.io/badge/platform-linux-green)
[![GitHub Repo Stars](https://img.shields.io/github/stars/youyve/nputop?label=stars&logo=github&color=brightgreen)](https://github.com/youyve/nputop/stargazers)
[![中文文档](https://img.shields.io/badge/Docs-中文-red)](README_zh.md)

---

`nputop` is an **interactive command-line tool** designed specifically for monitoring and managing processes running on **Ascend NPUs**. Inspired by the popular [nvitop](https://github.com/XuehaiPan/nvitop) project, `nputop` brings a similar, intuitive user experience to the Ascend NPU ecosystem, providing real-time insights into utilization, memory usage, temperature, power consumption, and more.

---

## 🌟 Key Features

* **Real-time monitoring**: Track NPU usage, memory status, temperature, and power draw.
* **Interactive UI**: Navigate with keyboard/mouse and manage processes effortlessly.
* **Process management**: View, select, and interact with running NPU processes directly.
* **Multi-NPU Support**: Efficiently manage multiple Ascend NPUs simultaneously.
* **CLI convenience**: Easy integration into terminal workflows with minimal setup.

---

## 📸 Screenshots

![](assets/nputop_2025_0507.jpg)


---

## ⚙️ Installation

**Prerequisites:**

* Python ≥ 3.7
* Ascend NPU Drivers and Runtime Environment ([CANN](https://www.hiascend.com/software/cann/commercial))

```bash
pip install ascend-nputop
```

For development or editable installations:

```bash
git clone https://github.com/youyve/nputop.git
cd nputop
pip install -e .
```

---

## 🚀 Quick Start

Launch `nputop` directly from your terminal:

```bash
nputop
```

set environment variables (`ASCEND_RT_VISIBLE_DEVICES`) to restrict visible NPUs.

---

## 🔑 Usage & Shortcuts

* Navigate screens: <kbd>←</kbd> <kbd>→</kbd> or <kbd>TAB</kbd>
* Sort columns: <kbd>S</kbd>
* Toggle compact mode: <kbd>C</kbd>
* Kill a process: select a process and press <kbd>K</kbd>
* Refresh manually: <kbd>R</kbd>
* Exit: <kbd>Q</kbd> or <kbd>Ctrl</kbd>+<kbd>C</kbd>

---

## 🛠️ Project Structure

```
nputop
├── assets/             # Images for documentation
├── nputop/
│   ├── api/            # Ascend NPU APIs & backend
│   ├── gui/            # Interactive UI (GPL-3.0-only)
│   ├── cli.py          # Command-line entry point
│   └── version.py      # Versioning and metadata
├── COPYING             # GPL-3.0 License file
├── LICENSE             # Apache 2.0 License file
├── NOTICE              # Acknowledgments and Notices
├── pyproject.toml      # Project configuration
├── setup.py            # Build script
└── README.md           # Documentation
```

---

## 📋 Known Issues & Roadmap

* 🚧 **Slow startup** compared to GPU-based solutions.
* 🚧 **Incomplete parameter display** for some NPU metrics.
* 🚧 **Delayed utilization (UTL) refresh rate** and real-time process tracking issues.

These performance issues and feature gaps are being actively addressed in ongoing development iterations. Contributions are highly encouraged to help us improve `nputop`.

---

## 🤝 Contributing

We warmly welcome contributions! Feel free to:

* Report bugs and request features via [Issues](https://github.com/youyve/nputop/issues).
* Fork the repository and submit pull requests.
* Improve documentation and examples.

---

## 📃 License

This project (`nputop`) is derived from the original project [`nvitop`](https://github.com/XuehaiPan/nvitop) by Xuehai Pan.

The licenses applied are:

* **API Modules:** [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
* **GUI Modules:** [GNU General Public License v3.0 only](https://www.gnu.org/licenses/gpl-3.0.html)

```
Copyright (c) 2025 Xuehai Pan <XuehaiPan@pku.edu.cn>
Copyright (c) 2025 Lianzhong You <youlianzhong@gml.ac.cn>
```

For full details, see [LICENSE](LICENSE), [COPYING](COPYING), and [NOTICE](NOTICE).

---

## 📧 Contact

* **Maintainer:** [Lianzhong You](mailto:youlianzhong@gml.ac.cn)

---

Enjoy monitoring your Ascend NPUs with `nputop`! 🎉
