qtop is a scheduler-independent observability layer for HPC clusters, with an extremely fast terminal interface. It is a portable, dependency-light cluster observability and scheduler debugging tool for Slurm, PBS, SGE and OAR - and even more, with your contributed plugin effort.
See your whole cluster in one terminal. Capture it. Replay it. Compare it.
Schedulers expose a great deal of information, but their native commands rarely provide one concise view of jobs, queues, nodes, states and core occupancy. qtop turns scheduler output into a consistent terminal dashboard that is useful during daily operations and incident analysis.
- See cluster utilization, queues, users, node states and per-core job placement.
- Use the same interface across Slurm, PBS/Torque, SGE and OAR.
- Filter, sort, highlight, transpose and navigate large worker-node matrices interactively.
- Capture scheduler output for bug reports or offline investigation.
- Replay recent frames to understand scheduling changes over time.
- Export normalized cluster data as JSON.
- Run without a resident service, database, or heavy runtime dependency stack.
See the Quickstart guide for a short walkthrough from the demo to live monitoring, saved traces and support snapshots.
Clone the repository and launch the built-in demo:
git clone https://github.com/qtop/qtop.git
cd qtop
./qtop -b demo -FGTwOn a scheduler host, qtop can normally discover the available scheduler:
./qtop -wSelect it explicitly when needed:
./qtop -b slurm -w
./qtop -b slurm_json -w
./qtop --slurm-summary -w
./qtop -b pbs -w
./qtop -b sge -w
./qtop -b oar -wThe optional value after -w is the refresh interval in seconds. For example, -w 10 refreshes every ten seconds; without a value, watch mode refreshes every two seconds.
Run ./qtop --help for the complete command-line reference. While watch mode is active, press ? for the interactive key map.
git clone https://github.com/qtop/qtop.git
cd qtop
./qtop --versionTo install a checkout instead of running it directly, use a virtual environment
and python -m pip install .. Python 3.6-3.8 use a legacy-compatible build
backend; modern Python uses the metadata in pyproject.toml.
python3 -m pip install --user qtop
$HOME/.local/bin/qtop --versionPyPI currently serves qtop's legacy 2016 release. Until the next release is
published, install from source for current Slurm support and recent fixes. A
system-wide or virtual-environment installation can omit --user.
Read scheduler traces from a directory instead of invoking live commands:
./qtop -b slurm -s /path/to/slurm-tracesCreate a support sample containing qtop output, logs and scheduler traces
(use -L -A for a reproducible anonymized state snapshot):
./qtop -LReproduce an anonymized support archive with qtop --load-sample archive.tar.
This restores parsed state and presentation without contacting the scheduler.
Replay automatically captured frames from a specific time:
./qtop -R 1823Export the normalized cluster state to a JSON file in the configured save directory:
./qtop -E-E keeps the terminal view on stdout. See the
capture and export guide for
filenames, a real JSON example, archive contents and anonymization limits.
See the full documentation for trace filenames, configuration, filtering, replay formats, anonymization and scheduler-specific notes.
qtop separates scheduler-specific collection and parsing from a common cluster-state model and terminal presentation:
- A scheduler plugin collects live command output or reads saved traces.
- The plugin normalizes jobs, nodes and queues into a shared cluster state.
- qtop renders that state in a fast terminal view or exports it for other tools.
This design keeps the core scheduler-independent and makes support for another batch system a bounded plugin contribution.
See the architecture diagram and source map for the module relationships and the paths through collection, rendering, capture and replay.
qtop targets Python 3 and Linux-based HPC environments. Its CI matrix covers modern Python versions and retains a dependency-light compatibility lane for older enterprise distributions commonly found on clusters.
Terminal monitoring is the primary interface.
Maintainers and contributors can run make ci-deps once and make pre-pr
in a Linux x86-64 CPython 3.12 virtual environment to reproduce the local PR
gates, including coverage, type checks and both parser fuzzers. See
CONTRIBUTING.md for other platforms and Python 3.6 checks.
- User documentation and tutorial
- Contributing guide
- Maintenance roles, review routing and escalation
- Code of conduct
- Security policy
- Getting help
- OpenSSF metadata, badge preparation and future integrations
- Issue tracker
Bug reports with captured scheduler samples are especially valuable. New scheduler plugins, sample fixtures, documentation improvements and portability fixes are welcome.
AUTHORS: Original Bash version by Fotis Georgatos. Python port by Sotiris Fragkiskos. Additional authors: Evangelos Papadopoulos (push for 1.0) and Nicola Trozzi (admitted slurm support).
Full contributor credits: GitHub contributors.
License: MIT.