Installation

This guide will help you install gflow on your system.

Prerequisites

• Operating System: Linux (tested on Ubuntu 20.04+)
• tmux: Required for job execution
• NVIDIA GPU (optional): For GPU job scheduling
• NVIDIA drivers (optional): If using GPU features

Installing Prerequisites

Ubuntu/Debian

# Install tmux
sudo apt-get update
sudo apt-get install tmux

Fedora/RHEL

# Install tmux
sudo dnf install tmux

Installation Methods

Method 1: Install via PyPI (Recommended)

Install gflow using uv (recommended for CLI tools):

uv tool install runqd

Or using pipx:

pipx install runqd

Or using pip:

pip install runqd

This will install pre-built binaries for Linux (x86_64, ARM64).

Install Nightly Build

To try the latest development version, install from TestPyPI:

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

Method 2: Install via Cargo

Build and install from crates.io:

cargo install gflow

Or install from the main branch:

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

This will compile and install all binaries to ~/.cargo/bin/, which should be in your PATH.

Method 3: Build from Source

If you want to build from the latest source code:

1. Clone the repository:

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

2. Build the project:

   cargo build --release

   The executables will be in target/release/.

3. Install to system (optional):

   cargo install --path .

Verify Installation

After installation, verify that gflow is properly installed:

# Check if commands are available
which gflowd ginfo gbatch gqueue gcancel

# Verify version
gflowd --version

Sanity Check

1. tmux

Make sure tmux works:

tmux new-session -d -s test
tmux has-session -t test && echo "tmux is working!"
tmux kill-session -t test

2. Daemon + GPU detection (Optional)

If you have NVIDIA GPUs, verify they're detected:

# (Optional) Create a config file with sensible defaults
gflowd init

# Start the daemon
gflowd up

# Verify it started
gflowd status

Check system info and GPU allocation:

ginfo

The daemon shows GPU information if NVIDIA GPUs are available.

File Locations

gflow uses the following directories:

Location	Purpose
~/.config/gflow/gflow.toml	Configuration file (optional)
~/.local/share/gflow/state.json	Persistent job state
~/.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 to PATH if missing (add to ~/.bashrc or ~/.zshrc):

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

3. Reload shell:

   source ~/.bashrc  # or ~/.zshrc

Issue: GPU not detected

1. Check NVIDIA drivers:

   nvidia-smi

2. Verify NVML library:

   ldconfig -p | grep libnvidia-ml

3. If GPU detection fails, gflow will still work but won't manage GPU resources.

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:

# 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

Now that gflow is installed, head to the Quick Start Guide to learn how to use it!

---

Previous: Introduction | Next: Quick Start