# 🚀 Ground Control - The Ultimate Terminal System Monitor
[](https://badge.fury.io/py/groundcontrol)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://www.python.org/downloads/)
**Ground Control** is a sleek, real-time terminal-based system monitor built with [Textual](https://textual.textualize.io/), [Plotext](https://github.com/piccolomo/plotext) and the [nvitop API](https://terminaltrove.com/nvitop/). It provides a powerful, aesthetic, customizable interface for tracking CPU, memory, disk, network, GPU usage, and system temperatures — all in a visually appealing and responsive TUI.
**Ground Control** works optimally with [TMUX](https://github.com/tmux/tmux/wiki), install it [here](https://github.com/tmux/tmux/wiki/Installing)!
We tested **Ground Control** with the *Windows Terminal* app, *Tabby* and the *VSCode integrated terminal*. Monospaced fonts are preferred.
## 🌟 Features
### 📊 Real-Time System Monitoring
- **CPU Usage**: Per-core load tracking with frequency stats and detailed performance metrics.
- **Memory Utilization**: RAM usage with dynamic visualization and memory statistics.
- **Temperature Monitoring**: Real-time system temperature tracking with thermal status indicators.
- **Disk I/O**: Monitor read/write speeds and disk usage with comprehensive storage metrics.
- **Network Traffic**: Live upload/download speeds with bandwidth utilization graphs.
- **GPU Metrics**: Real-time NVIDIA GPU monitoring with utilization and memory tracking (if available).
### 🖥️ Responsive Layout
- **Automatic resizing** to fit your terminal window.
- **Multiple layouts**: Grid, Horizontal, and Vertical.
- **Customizable widgets**: Show only the metrics you need with granular control.
### 🎛️ Interactive Controls
- **Keyboard shortcuts** for quick navigation.
- **Toggle between different layouts** instantly.
- **Customize displayed metrics** via a built-in selection panel with individual widget control.
---
## 🛠️ Installation
### 🔹 Install via PyPI
```sh
pip install ground-control-tui
```
### 🔹 Install from Source
```sh
git clone https://github.com/alberto-rota/ground-control
cd ground-control
pip install -e .
```
---
## 🚀 Getting Started
### 🔹 Run Ground Control
Once installed, simply launch Ground Control with:
```sh
groundcontrol
```
or
```sh
gc
```
### 🔹 Available Layouts
### Grid Layout
A structured layout displaying all widgets neatly in a grid. When you first launch **Ground Control**, it will show this layout.
### Horizontal Layout
All widgets aligned in a single row. If you like working with wide shell spaces, split a TMUX session horizontally and use this layout!
#### Vertical Layout
A column-based layout, ideal for narrow shell spaces. If you like working with tall shell spaces, split a TMUX session verticall and use this layout!
### 🖥️ Widget Breakdown
Each panel in Ground Control represents a different system metric:
### 🔹 **CPU Usage**
- Shows per-core CPU usage as horizontal bars (0-100%)
- Displays each core's utilization in a compact bar chart format
- Updates in real-time with color-coded bars showing load intensity
<img src="https://github.com/alberto-rota/ground-control/blob/main/assets/cpus.png?raw=true" alt="CPU_widget" width="600">
### 🔹 **Memory Utilization**
- Dual plot showing RAM (positive axis) and SWAP (negative axis) usage in GB
- Center bar with color-coded sections showing used/free RAM and SWAP
- Title displays total RAM and SWAP capacity in GB
<img src="https://github.com/alberto-rota/ground-control/blob/main/assets/ram.png?raw=true" alt="RAM_widget" width="600">
### 🔹 **Temperature Monitoring**
- Multi-line plot tracking temperature over time in °C for up to 4 key sensors
- Color-coded warning thresholds at 60°C (orange) and 80°C (red)
- Right panel shows current temperatures with dynamic color bars based on heat levels
- Prioritizes CPU, GPU, and motherboard sensors
<img src="https://github.com/alberto-rota/ground-control/blob/main/assets/temperature.png?raw=true" alt="Temperature_widget" width="600">
### 🔹 **Disk I/O**
- Dual plot showing read (positive axis) and write (negative axis) speeds for each mounted disk/partition
- Shows disk usage with color-coded bar for used/free space in GB
- Updates in real-time with throughput history
- Each mounted disk/partition gets its own widget (except boot/EFI partitions)
- Automatically detects and displays all mounted disks and partitions
<img src="https://github.com/alberto-rota/ground-control/blob/main/assets/disk.png?raw=true" alt="Disk_widget" width="600">
### 🔹 **Network Traffic**
- Dual plot showing upload (positive axis) and download (negative axis) speeds
- Shows current transfer rates with color-coded indicators
- Tracks cumulative data transfer amounts
<img src="https://github.com/alberto-rota/ground-control/blob/main/assets/network.png?raw=true" alt="Network_widget" width="600">
### 🔹 **GPU Metrics (NVIDIA Only)**
- Dual plot showing GPU usage % (positive axis) and memory usage GB (negative axis)
- Center bar displays current GPU memory usage (GB) and utilization (%)
- Shows "Usage UNAV" when GPU utilization cannot be detected
<img src="https://github.com/alberto-rota/ground-control/blob/main/assets/gpu.png?raw=true" alt="GPU_widget" width="600">
## 🛠️ Configuring Ground Control
Ground Control offers extensive customization options to tailor your monitoring experience. You might not want to see all the widgets all at once, or you may want to focus on specific system metrics.
### 🔹 **Widget Selection Panel**
The configuration panel can be accessed by pressing `c` or clicking the `Configure` button. This opens a panel that allows you to:
- **Toggle widgets**: Enable/disable individual widgets (CPU, Memory, Temperature, Disk, Network, GPU) by clicking their checkboxes
- **Refresh rate**: Choose update intervals from 500ms to 1 minute using the refresh rate buttons
- **History size**: Set the data history length from 30 seconds to 10 minutes using the history buttons
- **Save preferences**: All settings are automatically saved to `~/.config/ground-control/config.json`
The config file stores:
- Widget visibility settings for each widget
- Current layout (grid/horizontal/vertical)
- Refresh rate in seconds
- History size in seconds
### 🔹 **Layout Management**
You can switch between different layouts instantly:
- Press `g` or click `Grid Layout` for the structured grid view
- Press `h` or click `Horizontal Layout` for single-row alignment
- Press `v` or click `Vertical Layout` for column-based display
### 🔹 **Persistent Configuration**
All your customizations are automatically saved when you quit Ground Control. When you launch it again, you'll see the same layout and widget configuration you previously selected, ensuring a consistent monitoring experience.
### 🔹 **Keyboard Shortcuts**
All available keyboard shortcuts are listed here:
| Key | Action |
|------|--------|
| `h` | Switch to Horizontal Layout |
| `v` | Switch to Vertical Layout |
| `g` | Switch to Grid Layout |
| `c` | Show/Hide the configuration panel |
| `q` | Quit Ground Control |
---
**Ground Control** saves user preferences in a configuration file located at:
`
~/.config/ground-control/config.json
`.
Modify this file in your default text editor with
```sh
groundcontrol config
```
or
```sh
gc config
```
## ⛔ Current Known Limitations/Bugs
- In heavy-duty HPC systems, with multiple disks, cores and GPUs to be monitored, metric collection and plotting might get bottlenecked and groundcontrol might run slow. Consider **directly editing the config file with a text editor** to avoid
- GPU usage is monitored only for CUDA-enabled hardware. Ground Control detects MiG devices but in some cases it cannot detect their utilization. You'll see *Usage UNAV* in the GPU Widget if this is the case
- Temperature monitoring availability depends on system sensors and may not be available on all platforms
## 👨💻 Contributing
Pull requests and contributions are welcome! To contribute:
1. Fork the repo.
2. Create a feature branch.
3. Submit a PR with your changes.
Visit the [Issue Section](https://github.com/alberto-rota/ground-control/issues) to start!
## 📜 License
This project is licensed under the **GNU General Public License v3.0**. See the [LICENSE](LICENSE) file for details.
## 📧 Author
**Alberto Rota**
📩 Email: alberto_rota@outlook.com
🐙 GitHub: [@alberto-rota](https://github.com/alberto-rota)
Raw data
{
"_id": null,
"home_page": "https://github.com/alberto-rota/ground-control",
"name": "ground-control-tui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Alberto Rota",
"author_email": "alberto1.rota@polimi.it",
"download_url": "https://files.pythonhosted.org/packages/62/ab/4d142d588a2c445049b9caa6f8fb044d9ea225f87baed69f2fdc272be04f/ground_control_tui-1.2.0.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 Ground Control - The Ultimate Terminal System Monitor\n\n\n\n[](https://badge.fury.io/py/groundcontrol)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://www.python.org/downloads/)\n\n**Ground Control** is a sleek, real-time terminal-based system monitor built with [Textual](https://textual.textualize.io/), [Plotext](https://github.com/piccolomo/plotext) and the [nvitop API](https://terminaltrove.com/nvitop/). It provides a powerful, aesthetic, customizable interface for tracking CPU, memory, disk, network, GPU usage, and system temperatures \u2014 all in a visually appealing and responsive TUI.\n\n**Ground Control** works optimally with [TMUX](https://github.com/tmux/tmux/wiki), install it [here](https://github.com/tmux/tmux/wiki/Installing)!\n\nWe tested **Ground Control** with the *Windows Terminal* app, *Tabby* and the *VSCode integrated terminal*. Monospaced fonts are preferred. \n\n## \ud83c\udf1f Features\n\n### \ud83d\udcca Real-Time System Monitoring\n- **CPU Usage**: Per-core load tracking with frequency stats and detailed performance metrics.\n- **Memory Utilization**: RAM usage with dynamic visualization and memory statistics.\n- **Temperature Monitoring**: Real-time system temperature tracking with thermal status indicators.\n- **Disk I/O**: Monitor read/write speeds and disk usage with comprehensive storage metrics.\n- **Network Traffic**: Live upload/download speeds with bandwidth utilization graphs.\n- **GPU Metrics**: Real-time NVIDIA GPU monitoring with utilization and memory tracking (if available).\n\n### \ud83d\udda5\ufe0f Responsive Layout\n- **Automatic resizing** to fit your terminal window.\n- **Multiple layouts**: Grid, Horizontal, and Vertical.\n- **Customizable widgets**: Show only the metrics you need with granular control.\n\n### \ud83c\udf9b\ufe0f Interactive Controls\n- **Keyboard shortcuts** for quick navigation.\n- **Toggle between different layouts** instantly.\n- **Customize displayed metrics** via a built-in selection panel with individual widget control.\n\n---\n\n## \ud83d\udee0\ufe0f Installation\n\n### \ud83d\udd39 Install via PyPI\n```sh\npip install ground-control-tui\n```\n\n### \ud83d\udd39 Install from Source\n```sh\ngit clone https://github.com/alberto-rota/ground-control\ncd ground-control\npip install -e .\n```\n\n---\n\n## \ud83d\ude80 Getting Started\n\n### \ud83d\udd39 Run Ground Control\nOnce installed, simply launch Ground Control with:\n```sh\ngroundcontrol\n```\nor \n```sh\ngc\n```\n\n### \ud83d\udd39 Available Layouts\n\n### Grid Layout\nA structured layout displaying all widgets neatly in a grid. When you first launch **Ground Control**, it will show this layout.\n\n\n### Horizontal Layout\nAll widgets aligned in a single row. If you like working with wide shell spaces, split a TMUX session horizontally and use this layout!\n\n\n#### Vertical Layout\nA column-based layout, ideal for narrow shell spaces. If you like working with tall shell spaces, split a TMUX session verticall and use this layout!\n\n\n### \ud83d\udda5\ufe0f Widget Breakdown\nEach panel in Ground Control represents a different system metric:\n\n### \ud83d\udd39 **CPU Usage**\n- Shows per-core CPU usage as horizontal bars (0-100%)\n- Displays each core's utilization in a compact bar chart format\n- Updates in real-time with color-coded bars showing load intensity\n\n<img src=\"https://github.com/alberto-rota/ground-control/blob/main/assets/cpus.png?raw=true\" alt=\"CPU_widget\" width=\"600\">\n\n### \ud83d\udd39 **Memory Utilization**\n- Dual plot showing RAM (positive axis) and SWAP (negative axis) usage in GB\n- Center bar with color-coded sections showing used/free RAM and SWAP\n- Title displays total RAM and SWAP capacity in GB\n\n<img src=\"https://github.com/alberto-rota/ground-control/blob/main/assets/ram.png?raw=true\" alt=\"RAM_widget\" width=\"600\">\n\n### \ud83d\udd39 **Temperature Monitoring**\n- Multi-line plot tracking temperature over time in \u00b0C for up to 4 key sensors\n- Color-coded warning thresholds at 60\u00b0C (orange) and 80\u00b0C (red)\n- Right panel shows current temperatures with dynamic color bars based on heat levels\n- Prioritizes CPU, GPU, and motherboard sensors\n\n<img src=\"https://github.com/alberto-rota/ground-control/blob/main/assets/temperature.png?raw=true\" alt=\"Temperature_widget\" width=\"600\">\n\n### \ud83d\udd39 **Disk I/O**\n- Dual plot showing read (positive axis) and write (negative axis) speeds for each mounted disk/partition\n- Shows disk usage with color-coded bar for used/free space in GB\n- Updates in real-time with throughput history\n- Each mounted disk/partition gets its own widget (except boot/EFI partitions)\n- Automatically detects and displays all mounted disks and partitions\n\n<img src=\"https://github.com/alberto-rota/ground-control/blob/main/assets/disk.png?raw=true\" alt=\"Disk_widget\" width=\"600\">\n\n### \ud83d\udd39 **Network Traffic**\n- Dual plot showing upload (positive axis) and download (negative axis) speeds\n- Shows current transfer rates with color-coded indicators\n- Tracks cumulative data transfer amounts\n\n<img src=\"https://github.com/alberto-rota/ground-control/blob/main/assets/network.png?raw=true\" alt=\"Network_widget\" width=\"600\">\n\n### \ud83d\udd39 **GPU Metrics (NVIDIA Only)**\n- Dual plot showing GPU usage % (positive axis) and memory usage GB (negative axis)\n- Center bar displays current GPU memory usage (GB) and utilization (%)\n- Shows \"Usage UNAV\" when GPU utilization cannot be detected\n\n<img src=\"https://github.com/alberto-rota/ground-control/blob/main/assets/gpu.png?raw=true\" alt=\"GPU_widget\" width=\"600\">\n\n## \ud83d\udee0\ufe0f Configuring Ground Control\nGround Control offers extensive customization options to tailor your monitoring experience. You might not want to see all the widgets all at once, or you may want to focus on specific system metrics.\n\n### \ud83d\udd39 **Widget Selection Panel**\nThe configuration panel can be accessed by pressing `c` or clicking the `Configure` button. This opens a panel that allows you to:\n\n- **Toggle widgets**: Enable/disable individual widgets (CPU, Memory, Temperature, Disk, Network, GPU) by clicking their checkboxes\n- **Refresh rate**: Choose update intervals from 500ms to 1 minute using the refresh rate buttons\n- **History size**: Set the data history length from 30 seconds to 10 minutes using the history buttons\n- **Save preferences**: All settings are automatically saved to `~/.config/ground-control/config.json`\n\nThe config file stores:\n- Widget visibility settings for each widget\n- Current layout (grid/horizontal/vertical) \n- Refresh rate in seconds\n- History size in seconds\n\n### \ud83d\udd39 **Layout Management**\nYou can switch between different layouts instantly:\n- Press `g` or click `Grid Layout` for the structured grid view\n- Press `h` or click `Horizontal Layout` for single-row alignment\n- Press `v` or click `Vertical Layout` for column-based display\n\n\n\n### \ud83d\udd39 **Persistent Configuration**\nAll your customizations are automatically saved when you quit Ground Control. When you launch it again, you'll see the same layout and widget configuration you previously selected, ensuring a consistent monitoring experience.\n\n### \ud83d\udd39 **Keyboard Shortcuts**\nAll available keyboard shortcuts are listed here:\n| Key | Action |\n|------|--------|\n| `h` | Switch to Horizontal Layout |\n| `v` | Switch to Vertical Layout |\n| `g` | Switch to Grid Layout |\n| `c` | Show/Hide the configuration panel |\n| `q` | Quit Ground Control |\n\n---\n\n**Ground Control** saves user preferences in a configuration file located at:\n`\n~/.config/ground-control/config.json\n`.\nModify this file in your default text editor with\n```sh\ngroundcontrol config\n```\nor \n\n```sh\ngc config\n```\n\n## \u26d4 Current Known Limitations/Bugs\n- In heavy-duty HPC systems, with multiple disks, cores and GPUs to be monitored, metric collection and plotting might get bottlenecked and groundcontrol might run slow. Consider **directly editing the config file with a text editor** to avoid \n- GPU usage is monitored only for CUDA-enabled hardware. Ground Control detects MiG devices but in some cases it cannot detect their utilization. You'll see *Usage UNAV* in the GPU Widget if this is the case\n- Temperature monitoring availability depends on system sensors and may not be available on all platforms\n\n## \ud83d\udc68\u200d\ud83d\udcbb Contributing\nPull requests and contributions are welcome! To contribute:\n1. Fork the repo.\n2. Create a feature branch.\n3. Submit a PR with your changes.\n\nVisit the [Issue Section](https://github.com/alberto-rota/ground-control/issues) to start!\n\n## \ud83d\udcdc License\nThis project is licensed under the **GNU General Public License v3.0**. See the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udce7 Author\n**Alberto Rota** \n\ud83d\udce9 Email: alberto_rota@outlook.com \n\ud83d\udc19 GitHub: [@alberto-rota](https://github.com/alberto-rota)\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A Python Textual app for monitoring hardware in the terminal",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/alberto-rota/ground-control"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b08503771f86a4d0ee16616c367518a30842448aa3711787ad9334c0bc194f6c",
"md5": "4c3d3c0ef9a7aca76ee54977f3ac3525",
"sha256": "8074c8666d96c45b3af8b0d4eae6b59283d62ed3d28ba0921f6583261cd55109"
},
"downloads": -1,
"filename": "ground_control_tui-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c3d3c0ef9a7aca76ee54977f3ac3525",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 50600,
"upload_time": "2025-07-10T15:51:57",
"upload_time_iso_8601": "2025-07-10T15:51:57.952871Z",
"url": "https://files.pythonhosted.org/packages/b0/85/03771f86a4d0ee16616c367518a30842448aa3711787ad9334c0bc194f6c/ground_control_tui-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "62ab4d142d588a2c445049b9caa6f8fb044d9ea225f87baed69f2fdc272be04f",
"md5": "0f522a045cfda84ac144e7cea23b488e",
"sha256": "eb61a1fc2f9c5318d0f62b7ad9834c82013d50c6ee2db716dddbe7ab4ff44179"
},
"downloads": -1,
"filename": "ground_control_tui-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "0f522a045cfda84ac144e7cea23b488e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 47186,
"upload_time": "2025-07-10T15:51:59",
"upload_time_iso_8601": "2025-07-10T15:51:59.184671Z",
"url": "https://files.pythonhosted.org/packages/62/ab/4d142d588a2c445049b9caa6f8fb044d9ea225f87baed69f2fdc272be04f/ground_control_tui-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 15:51:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alberto-rota",
"github_project": "ground-control",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "nvidia_ml_py",
"specs": [
[
"==",
"12.570.86"
]
]
},
{
"name": "nvitop",
"specs": [
[
"==",
"1.4.2"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.3.6"
]
]
},
{
"name": "plotext",
"specs": [
[
"==",
"5.3.2"
]
]
},
{
"name": "psutil",
"specs": [
[
"==",
"6.1.1"
]
]
},
{
"name": "pynvml",
"specs": [
[
"==",
"11.5.3"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"75.1.0"
]
]
},
{
"name": "textual",
"specs": [
[
"==",
"1.0.0"
]
]
}
],
"lcname": "ground-control-tui"
}
JSON
