Installation

Install gflow with the steps below.

Package Name

The Python package name is runqd. It provides gflowd, gbatch, gqueue, gjob, ginfo, gcancel, and gctl.

Prerequisites

• Operating System: Linux
• tmux: Required for the default job executor and for gflowd up/attach workflows. The tmux-free process executor remains available as an opt-in via [executor] type = "process"
• NVIDIA GPU / drivers: Only required for GPU scheduling

Installing Prerequisites

Ubuntu/Debian

# tmux is required for the default tmux job executor and tmux-hosted daemon
sudo apt-get update
sudo apt-get install tmux

Fedora/RHEL

# tmux is required for the default tmux job executor and tmux-hosted daemon
sudo dnf install tmux

Installation Methods

Method 1: Install via PyPI (Recommended)

Use uv or pipx for CLI installs:

uv

uv tool install runqd

pipx

pipx install runqd

pip

pip install runqd

Pre-built binaries are available for Linux x86_64 and ARM64.

Install Nightly Build

For the latest development build, install from TestPyPI:

uv

uv tool install --index https://test.pypi.org/simple/ runqd

pipx

pipx install --index-url https://test.pypi.org/simple/ runqd

pip

pip install --index-url https://test.pypi.org/simple/ runqd

Method 2: Install via Cargo

Build and install from crates.io:

crates.io

cargo install gflow

main branch

cargo install --git https://github.com/AndPuQing/gflow.git --locked

This installs binaries to ~/.cargo/bin/. Make sure it is in your PATH.

Method 3: Build from Source

To build from source:

1. Clone the repository:

   git clone https://github.com/AndPuQing/gflow.git
   cd gflow

2. Build the project:

   cargo build --release

   Executables will be in target/release/.

3. Install to the system (optional):

   cargo install --path .

Verify Installation

After installation, check the commands and version:

# Check commands
which gflowd ginfo gbatch gqueue gcancel

# Check version
gflowd --version

TIP

If the commands work and gflowd --version prints a version, the install is complete.

Run Checks

1. Check the daemon (no tmux required)

Job execution no longer requires tmux: the daemon spawns each job as a detached child process group and redirects its output to logs/<job_id>.log. gflowd start hosts the daemon via the systemd user service when installed, otherwise in tmux when available, otherwise as a direct detached process.

# Optional: create a default config
gflowd init

# Start the daemon
gflowd start

# Check status
gflowd status

Optional: systemd user service (auto-start + crash recovery)

On Linux with a systemd user manager, install gflowd as a user service so it auto-starts on login and restarts automatically if it crashes:

gflowd service install
gflowd status        # shows "Hosting: systemd user service"

Remove it later with:

gflowd service uninstall

2. Check tmux (only if you use tmux features)

tmux new-session -d -s test
tmux has-session -t test && echo "tmux ok"
tmux kill-session -t test

3. Check the daemon and GPU detection (optional)

If you have NVIDIA GPUs, you can verify detection:

# Optional: create a default config
gflowd init

# Start the daemon
gflowd start

# Check status
gflowd status

Check system info and GPUs:

ginfo

If detection works, the output includes GPU information.

File Locations

gflow uses these directories:

Location	Purpose
~/.config/gflow/gflow.toml	Configuration file (optional)
~/.local/share/gflow/state.msgpack	Persistent job state (state.json is still read for legacy installs)
~/.local/share/gflow/logs/	Job output logs

Troubleshooting

Issue: Command not found

If you get "command not found" after installation:

1. Check if ~/.cargo/bin is in your PATH:

   echo $PATH | grep -o ~/.cargo/bin

2. Add it to ~/.bashrc or ~/.zshrc if missing:

   export PATH="$HOME/.cargo/bin:$PATH"

3. Reload the shell:

   source ~/.bashrc  # or ~/.zshrc

Issue: GPU not detected

1. Check NVIDIA drivers:

   nvidia-smi

2. Check the NVML library:

   ldconfig -p | grep libnvidia-ml

3. If detection fails, gflow still works for CPU jobs.

Updating gflow

If installed via Cargo

cargo install gflow --force

If built from source

cd gflow
git pull
cargo build --release
cargo install --path . --force

Uninstallation

To remove gflow:

WARNING

The optional data cleanup commands below permanently remove local scheduler state and logs.

# Stop the daemon first
gflowd down

# Uninstall binaries
cargo uninstall gflow

# Remove configuration and data (optional)
rm -rf ~/.config/gflow
rm -rf ~/.local/share/gflow

Next Steps

After installation, continue with Quick Start.