hpcrun — Submit a Batch Job Without Leaving Your Terminal

hpcrun turns a command you'd normally run interactively into a Slurm batch job, in one step, from inside your VS Code / desktop session's terminal. It's the tool behind the advice in Releasing GPUs Promptly: instead of holding your GPU for your whole session, submit the job, close the laptop lid, and the GPU frees up the moment the job finishes.

hpcrun python train.py

That's it — no job script to write, no #SBATCH lines to remember. Your partition and account are inherited automatically from the session you're running it in.

Why not just run it directly?

Because running it directly is the problem this solves — see Releasing GPUs Promptly for the full explanation. Short version: an interactive session holds its GPU for the entire walltime you requested, whether or not anything is actually running. hpcrun submits your command as its own batch job instead, so the GPU is only reserved while the command is actually executing.

Subcommands

Command	What it does
hpcrun [options] <command> [args...]	Submit <command> as a batch job (the default; no subcommand needed)
hpcrun status	Your queued/running jobs, plus anything finished in the last 2 days
hpcrun logs [-f] [jobid]	Show a job's output (-f follows live; defaults to your most recent job)
hpcrun cancel [jobid]	Cancel a job (defaults to your only running/queued one)
hpcrun version	Print the installed hpcrun version
hpcrun help	Full usage

Options

Flag	Default	What it does
--gpu <spec>	none	GPU request — see GPU requests below
--hours <n>	8	Walltime cap, in hours. The job ends when your command finishes; this only bounds how long it's allowed to run
--cpus <n>	4	CPU cores
--mem <n>	scales with --cpus	Memory override, e.g. --mem 64G
--name <name>	derived from your command	Job name shown in squeue
--here	off	Pin the job to the node you're running on right now (see Working directory)
--no-nas	off	Skip the AD password prompt — the job won't be able to read/write your lab's NAS shares
--partition <p>	inherited from your session	Override the partition
--dry-run	off	Print the job script and scheduler arguments without submitting anything — see below

GPU requests

--gpu value	What you get
(omitted)	No GPU
shared	One fractional GPU share (MPS) — fine for most jobs, and the considerate default when you don't need a whole card
1 (or any number)	That many whole GPUs, any model
h200 (or another model name your lab has)	One whole GPU of that specific model
h200:2	Two whole GPUs of that model
h200:shared	One fractional share, specifically on that model

hpcrun --gpu shared python train.py
hpcrun --gpu h200 --hours 24 python train.py --epochs 100

If you don't request a GPU, hpcrun reminds you at submit time — that's usually a sign you meant to add --gpu shared or --gpu 1.

Working directory

hpcrun runs your command in whatever directory you're in when you submit — but the job might land on a different node than the one you're on now. That means the directory has to be visible from every node:

• Your lab share (~/nas/..., ~/lab-research/..., or any /mnt/... path) — see Your Lab's Storage. This is the normal case; just cd into your project on lab storage before running hpcrun.
• Your home directory (~) does not qualify — it's local to whichever node you land on (see Your Lab's Storage). Running hpcrun from ~ gets a clear error telling you to move to lab storage or use --here.

If you genuinely need to run from a node-local path (e.g. you're testing against something on /scratch or local disk), pass --here — this pins the job to the node you're currently on instead of letting it land anywhere in your lab's partition.

cd ~/nas/my-project
hpcrun python train.py                 # portable — runs on any node

cd /scratch/$USER/local-test
hpcrun --here python train.py          # pinned to this node

NAS access from inside the job

If your command needs to read or write your lab's NAS shares (~/nas/...), hpcrun prompts once for your AD password at submit time — the same one-time, not-stored-to-disk handoff used everywhere else in the portal (see Your Lab's Storage). Hit enter to skip it if your job doesn't touch the NAS, or pass --no-nas to skip the prompt outright.

Preview before you submit

--dry-run prints exactly what would happen — the generated job script and the full sbatch argument list — without queuing anything. Useful for sanity-checking a GPU spec or working directory before committing a job to the queue:

hpcrun --dry-run --gpu h200:2 python train.py --epochs 100

Logs

Logs and the generated job script land under ~/hpcrun/ (a symlink to shared storage, separate from your lab's NAS — this is where hpcrun itself keeps its own bookkeeping, not a place for your research data). It shows up in your VS Code file tree automatically.

hpcrun logs -f          # follow your most recent job's output live
hpcrun logs 12345       # a specific job by ID

Checking on and cancelling jobs

hpcrun status            # queued/running, plus recently finished
hpcrun cancel             # cancels your only job, if you have exactly one
hpcrun cancel 12345       # cancel a specific job

If you have more than one job running, hpcrun cancel (with no ID) lists them and asks you to specify which one.

Full example

cd ~/nas/my-project
hpcrun --gpu shared --hours 12 --name train-run1 python train.py --epochs 50
# Submitted job 12345 (train-run1) to partition inspire
#   log:     ~/hpcrun/train-run1-12345.log   (created when the job starts)
#   follow:  hpcrun logs -f
#   status:  hpcrun status

hpcrun logs -f            # watch it run
hpcrun status              # check queue state any time
hpcrun cancel 12345        # or cancel it early if needed