qstat(1B)

📦 version 23.06.06-unstable-2026-04, in nixos 26.05, nixpkgs unstable

💅 qstat(1B) — the PBS Professional glow-up

okay bestie, welcome to qstat(1B) from PBS Professional — this is the page where you learn to see your jobs, queues, and servers. it's literally the vibe check for your whole cluster. let's go ✨

🌸 NAME

qstat — display status of PBS jobs, queues, or servers

🎀 SYNOPSIS

no cap, the synopsis is the biggest part, so we're breaking it into lil groups. stay with me 🫶

💜 Displaying Job Status

Default format:

qstat [-E] [-J] [-p] [-t] [-w] [-x] [[<job ID> | <destination>]
...]

Long format:

qstat -f [-F json | dsv [-D <delimiter>]] [-E] [-J] [-p] [-t]
[-w]
      [-x] [[<job ID> | <destination>] ...]

Alternate format:

qstat [-a | -H | -i | -r ] [-E] [-G | -M] [-J] [-n [-1]]
      [-s [-1]] [-t] [-T] [-u <user list>] [-w]
      [[<job ID> | <destination>] ...]

🦋 Displaying Queue Status

Default format:

qstat -Q [<destination> ...]

Long format:

qstat -Q -f [-F json | dsv [-D <delimiter>]] [-w] [<destination>
...]

Alternate format:

qstat -q [-G | -M] [<destination> ...]

🌈 Displaying Server Status

Default format:

qstat -B [<server> ...]

Long format:

qstat -B -f [-F json | dsv [-D <delimiter>]] [-w] [<server> ...]

⭐ Version Information

qstat --version

👑 DESCRIPTION

the qstat command displays the status of jobs, queues, or servers, and writes that status info to standard output. periodt.

when it's showing job status, qstat displays status info about all specified jobs, job arrays, and subjobs. you can name jobs by ID, or by destination — like, say, all jobs at a specified queue or server. iykyk 💅

🧚 Display Formats

you get to pick your format with particular options: a default format, an alternate format, or a long format. default and alternate formats show all the status info for a job, queue, or server with one line per object, all in columns. long formats show status info with all attributes, one attribute to a line. choose your fighter ✨

🍓 Displaying Information for Finished and Moved Jobs

you can display status info for finished and moved jobs by using the -x and -H options.

if your job got moved to another server through peer scheduling, give the job ID as an argument to qstat. if you don't specify the job ID, your job will not appear to exist 😭 (dramatic but true). for example, your job 123.ServerA is moved to ServerB. in this case, you can use

qstat 123

or

qstat 123.ServerA

specifying the full job name, including the server, avoids the possibility that qstat will report on a job named 123.ServerB that was moved to ServerA. 🙈

to list all jobs at ServerB, you can use:

qstat @ServerB

🎀 Displaying Truncated Data

when the number of characters required would exceed the space available, qstat truncates the output and puts an asterisk ("*") in the last position. for example, in default job display format, there are three characters allowed for the number of cores. if the actual output were 1234 , the value displayed would be 12* instead. it's giving "we ran out of room bestie" 💀

🔥 Required Privilege

users without Manager or Operator privilege cannot view resources or attributes that are invisible to unprivileged users. no sneaky peeking 👀

💜 DISPLAYING JOB STATUS

🌸 Job Status in Default Format

Triggers: no options, or any of the -J, -p, -t, or -x options.

the qstat command displays job status in default format when you specify no options, or any of the -J, -p, -t, or -x, options. jobs are displayed one to a line, with these column headers:

Job ID   Name       User      Time Use S Queue
-------- ---------- --------- -------- - -----

Description of columns:

  • Job ID — width 17 without -w (that's 22 when max_job_sequence_id > 10 million), and 30 with -w. it's the Job ID assigned by PBS.
  • Name — width 16 without -w, 15 with -w. the job name specified by submitter.
  • User — width 16 without -w, 15 with -w. username of job owner.
  • Time Use or Percent Complete — width 8 without -w, 8 with -w. this is the CPU time used by the job. before the application has actually started running, for example during stage-in, this field is "0". at the point where the application starts accumulating cput, this field changes to "00:00:00". after that, every time the MoM polls for resource usage, the field is updated. the MoM on each execution host polls for the usage of all processes on her host belonging to the job. usage is summed. the polling interval is short when a job first starts running and lengthens to a maximum of 2 minutes. ⏱️ if you specify -p, the Time Use column is replaced with the percentage completed for the job. for a job array this is the percentage of subjobs completed. for a normal job, it is the percentage of allocated CPU time used.
  • S — width 1 without -w, 1 with -w. the job's state:
    • B — Array job has at least one subjob running
    • E — Job is exiting after having run
    • F — Job is finished
    • H — Job is held
    • M — Job was moved to another server
    • Q — Job is queued
    • R — Job is running
    • S — Job is suspended
    • T — Job is being moved to new location
    • U — Cycle-harvesting job is suspended due to keyboard activity
    • W — Job is waiting for its submitter-assigned start time to be reached
    • X — Subjob has completed execution or has been deleted
  • Queue — width 16 without -w, 15 with -w. the queue in which the job resides.

🦋 Job Status in Long Format

Trigger: the -f option.

if you specify the -f (full) option, full job status information for each job is displayed in this order:

  1. The job ID
  2. Each job attribute, one to a line
  3. The job's submission arguments
  4. The job's executable, in JSDL format
  5. The executable's argument list, in JSDL format

the job attributes are listed as <name> = <value> pairs. this includes the exec_host and exec_vnode strings. the full output can be very large — like, buckle up, this one's a scroll 😭

the exec_host string has the format:

<host1>/<T1>*<P1>[+<host2>/<T2>*<P2>+...]

where

  • T1 is the task slot number (the index) of the job on hostA.
  • P1 is the number of processors allocated to the job from host1. the number of processors allocated does not appear if it is 1.

the exec_vnode string has the format:

(<vnode1>:ncpus=<N1>:mem=<M1>)[+(<vnode2>:ncpus=<N2>:mem=<M2>)+...]

where

  • N1 is the number of CPUs allocated to that job on vnode1.
  • M1 is the amount of memory allocated to that job on vnode1.

🌈 Job Status in Alternate Format

Triggers: any of the -a, -i, -G, -H, -M, -n, -r, -s, -T, or -u <user list> options.

the qstat command displays job status in the alternate format if you specify any of the -a, -i, -G, -H, -M, -n, -r, -s, -T, or -u <user list> options. jobs are displayed one to a line. if jobs are running and the -n option is specified, or if jobs are finished or moved and the -H and -n options are specified, there is a second line for the exec_host string. ✨

Column headers:

                                              Req'd  Req'd   Elap
Job ID Username Queue Jobname SessID NDS TSK Memory Time  S Time
------ -------- ----- ------- ------ --- --- ------ ----- - ----

Description of columns:

  • Job ID — width 15 without -w (that's 20 when max_job_sequence_id > 10 million), and 30 with -w. the job ID assigned by PBS.
  • Username — width 8 without -w, 15 with -w. username of job owner.
  • Queue — width 8 without -w, 15 with -w. queue in which the job resides.
  • Jobname — width 10 without -w, 15 with -w. job name specified by submitter.
  • SessID — width 6 without -w, 8 with -w. session ID. appears only if the job is running. 👀
  • NDS — width 3 without -w, 4 with -w. number of chunks or vnodes requested by the job.
  • TSK — width 3 without -w, 5 with -w. number of CPUs requested by the job.
  • Req'd Memory — width 6 without -w, 6 with -w. amount of memory requested by the job.
  • Req'd Time — width 5 without -w, 5 with -w. if CPU time is requested, this shows CPU time. otherwise, shows walltime.
  • S — width 1 without -w, 1 with -w. the job's state. (see the listing above for default format 💅)
  • Elap Time or Est Start Time — width 5 without -w, 5 with -w. if CPU time is requested, this shows CPU time. otherwise, shows walltime. if you use the -P option, displays estimated start time for queued jobs, replacing the Elap Time field with the Est Start Time field. ⭐

💅 Grouping Jobs and Sorting by ID 💅

Trigger: the -E option. periodt.

Okay so bestie, the -E option is your new fave for sorting AND grouping jobs in qstat output. What it does: groups jobs by server, and displays each group by ascending ID. Bonus? it also improves qstat performance. Iconic behavior. Here's the vibe check on how -E changes things:

  • qstat (no job ID specified)
    • without -E: queries the default server and displays result
    • with -E: no change in behavior; same as without -E option
  • qstat <list of job IDs from single server>
    • without -E: displays results in the order specified
    • with -E: displays results in ascending ID order
  • qstat <job IDs at multiple servers>
    • without -E: displays results in the order they are specified
    • with -E: groups jobs by server. Displays each group in ascending order

✨ DISPLAYING QUEUE STATUS ✨

🎀 Queue Status in Default Format 🎀

Trigger: the -Q option by itself.

The qstat command displays queue status in the default format if the only option is -Q. Queue status is displayed one queue to a line, with these column headers:

Queue Max  Tot  Ena  Str Que  Run  Hld  Wat  Trn  Ext  Type
----- ---- ---- ---- --- ---- ---- ---- ---- ---- ---- ----

Description of columns, bestie, one by one:

  • Queue — queue name
  • Max — maximum number of jobs allowed to run concurrently in this queue
  • Tot — total number of jobs in the queue
  • Ena — whether the queue is enabled or disabled
  • Str — whether the queue is started or stopped
  • Que — number of queued jobs
  • Run — number of running jobs
  • Hld — number of held jobs
  • Wat — number of waiting jobs
  • Trn — number of jobs being moved (transiting)
  • Ext — number of exiting jobs
  • Type — type of queue: execution or routing

🦋 Queue Status in Long Format 🦋

Trigger: the -q and -f options together.

If you specify the -f (full) option with the -q option, full queue status information for each queue is displayed starting with the queue name, followed by each attribute, one to a line, as <name> = <value> pairs. very thorough of her tbh.

🌸 Queue Status: Alternate Format 🌸

Triggers: any of the -q, -G, or -M options.

The qstat command displays queue status in the alternate format if you specify any of the -q, -G, or -M options. Queue status is displayed one queue to a line, and the lowest line contains totals for some columns.

These are the alternate format queue status column headers:

Queue Memory CPU Time Walltime Node Run Que Lm State
----- ------ -------- -------- ---- --- --- -- -----

Description of columns:

  • Queue — queue name
  • Memory — maximum amount of memory that can be requested by a job in this queue
  • CPU Time — maximum amount of CPU time that can be requested by a job in this queue
  • Walltime — maximum amount of walltime that can be requested by a job in this queue
  • Node — maximum number of vnodes that can be requested by a job in this queue
  • Run — number of running and suspended jobs. Lowest row is total number of running and suspended jobs in all the queues shown
  • Que — number of queued, waiting, and held jobs. Lowest row is total number of queued, waiting, and held jobs in all the queues shown
  • Lm — maximum number of jobs allowed to run concurrently in this queue
  • State — state of this queue: E (enabled) or D (disabled), and R (running) or S (stopped)

👑 DISPLAYING SERVER STATUS 👑

💜 Server Status in Default Format 💜

Trigger: the -B option.

The qstat command displays server status if the only option given is -B. just the one option, okurrr.

Column headers for default server status output:

Server Max Tot Que Run Hld Wat Trn Ext Status
------ --- --- --- --- --- --- --- --- ------

Description of columns:

  • Server — name of server
  • Max — maximum number of jobs allowed to be running concurrently on the server
  • Tot — total number of jobs currently managed by the server
  • Que — number of queued jobs
  • Run — number of running jobs
  • Hld — number of held jobs
  • Wat — number of waiting jobs
  • Trn — number of transiting jobs
  • Ext — number of exiting jobs
  • Status — status of the server

🧚 Server Status in Long Format 🧚

Trigger: the -f option.

If you specify the -f (full) option, displays full server status information starting with the server name, followed by each server attribute, one to a line, as <name> = <value> pairs. Includes PBS version information. she's giving full disclosure, we love that.

💅 OPTIONS 💅

⭐ Generic Job Status Options ⭐

  • -E — Groups jobs by server and displays jobs sorted by ascending ID. When qstat is presented with a list of jobs, jobs are grouped by server and each group is displayed by ascending ID. This option also improves qstat performance.

🍓 Default Job Status Options 🍓

  • -J — Prints status information for job arrays (not subjobs).
  • -t — Displays status information for jobs, job arrays, and subjobs. When used with -J option, prints status information for subjobs only.
  • -p — The Time Use column is replaced with the percentage completed for the job. For an array job this is the percentage of subjobs completed. For a normal job, it is the percentage of allocated CPU time used.
  • -x — Displays status information for finished and moved jobs in addition to queued and running jobs.

🔥 Alternate Job Status Options 🔥

  • -a — All queued and running jobs are displayed. If a destination is specified, information for all jobs at that destination is displayed. If a job ID is specified, information about that job is displayed. Always specify this option before the -n or -s options, otherwise they will not take effect.
  • -H — Without a job identifier, displays information for all finished or moved jobs. If a job ID is given, displays information for that job regardless of its state. If a destination is specified, displays information for finished or moved jobs, or specified job(s), at destination.
  • -i — If a destination is given, information for queued, held or waiting jobs at that destination is displayed. If a job ID is given, information about that job is displayed regardless of its state.
  • -n — The exec_host string is listed on the line below the basic information. If the -1 option is given, the exec_host string is listed on the end of the same line. If using the -a option, always specify the -n option after -a, otherwise the -n option does not take effect.
  • -r — If a destination is given, information for running or suspended jobs at that destination is displayed. If a job ID is given, information about that job is displayed regardless of its state.
  • -s — Any comment added by the administrator or scheduler is shown on the line below the basic information. If the -1 option is given, the comment string is listed on the end of the same line. If using the -a option, always specify the -s option after -a, otherwise the -s option does not take effect.
  • -T — Displays estimated start time for queued jobs, replacing the Elap Time field with the Est Start Time field. Jobs with earlier estimated start times are displayed before those with later estimated start times.

Running jobs are displayed before other jobs. Running jobs are sorted by their stime attribute (start time).

Queued jobs whose estimated start times are unset (estimated.start_time = unset) are displayed after those with estimated start times, with estimated start time shown as a double dash ("--"). Queued jobs with estimated start times in the past are treated as if their estimated start times are unset.

If a job's estimated start time cannot be calculated, the start time is shown as a question mark ("?").

Time displayed is local to the qstat command. Current week begins on Sunday. (sunday scaries but make it scheduling ✨)

The following table shows the format for the Est Start Time field when the -w option is not used:

  • <HH>:<MM> — today — example: 15:34
  • <2-letter weekday> <HH> — within 7 days, but after today — example: We 15
  • <3-letter month name> — this calendar year, but after this week — example: Feb
  • <YYYY> — less than or equal to 5 years from today, after this year — example: 2018
  • >5yrs — more than 5 years from today — example: >5yrs

The following table shows the format for the Est Start Time field when the -w option is used:

Format              Job Est Start Time  Example
-------------------------------------------------------------
Today <HH>:<MM>     Today               Today 13:34
-------------------------------------------------------------
<Day> <HH>:<MM>     This week, but      Wed 15:34
                    after today
-------------------------------------------------------------
<Day> <Month>       This year, but      Wed Feb 10 15:34
<Daynum> <HH>:<MM>  after this week
-------------------------------------------------------------
<Day> <Month>       After this year     Wed Feb 10 2018 15:34
<Daynum> <YYYY>
<HH>:<MM>
-------------------------------------------------------------

So yeah bestie, that's the vibe check for estimated start times 💅 — it flexes the format based on how far out your job is. And side note: when you pair this with the -f option, it prints the full timezone-qualified start time. ✨

Oh, and lowkey important 🫶: estimated start time info can be made unavailable to unprivileged users. In that case, the estimated start time just, like, appears to be unset. Not a bug, it's giving permissions. 🙈

  • -u <user list> — if you give a destination, it shows status for jobs at that destination owned by the users in <user list>. But if you give a job ID instead? It shows status info for that job regardless of who owns it. Main character energy for that job ID tbh 👑

Format is <username>[@<hostname>][, <username>[@<hostname>], ...] — a comma-separated list, periodt.

You can wildcard hostnames, but not domain names. And if you don't specify a hostname at all, the username is for any host. 🌈

  • -w — works with job status in default and alternate formats. It lets you see wider fields, up to 120 characters. (Peep "Job Status in Default Format" and "Job Status in Alternate Format" for the column widths, iykyk.)
⚠️ Heads up bestie: this <yellow>-w</yellow> is not the same -w as the one used with the -f long-format option. Two different -ws, same name, no cap. 💀
  • -1 (hyphen one) — reformats qstat output onto a single line. It can only be used in conjunction with the -n and/or -s options. No solo runs, sorry babe. 🙅

✨ Queue Status Options ✨

  • -Q — displays queue status in default format. Operands must be destinations. 🎀
  • -q — displays queue status in alternate format. Operands must be destinations. 🦋

✨ Server Status Options ✨

  • -B — display server status. Operands must be names of servers. 🌸

✨ Job, Queue, and Server Status Options ✨

  • -f [-w] — full display for long format. Job, queue or server attributes get displayed one to a line. Iconic, honestly. 👑

JSON output: PBS reports resources_used values for resources that are created or set in a hook as JSON strings in the output of qstat -f.

If MoM returns a JSON object (a Python dictionary), PBS reports the value as a string in single quotes:

resources_used.<resource_name> = '{ <mom_JSON_item_value>,
<mom_JSON_item_value>, <mom_JSON_item_value>, ..}'

Example: MoM returns { "a":1, "b":2, "c":1,"d": 4} for resources_used.foo_str. We get:

resources_used.foo_str='{"a": 1, "b": 2, "c":1,"d": 4}'

If MoM returns a value that is not a valid JSON object, the value is reported verbatim.

Example: MoM returns "hello" for resources_used.foo_str. We get:

resources_used.foo_str="hello"

Optional -w prints each attribute on one unbroken line. Feed characters get converted, bestie:

  • Newline is converted to backslash concatenated with "n", resulting in "\n"
  • Form feed is converted to backslash concatenated with "f", resulting in "\f"
🫶 Reminder: this <yellow>-w</yellow> is independent of the -w job output option used with default and alternate formats. Yes, again. Three -ws in this manpage, we stay confused but we stay slaying.
  • -F dsv [-D <delimiter>] — prints output in delimiter-separated value format. The default delimiter is a pipe ("|"). You can specify a character or a string delimiter using the -D argument to the -F dsv option. For example, to use a comma as the delimeter:
qstat -f -F dsv -D,

If the delimiter itself appears in a value, it gets escaped:

  • On Linux, the delimiter is escaped with a backslash ("\").
  • On Windows, the delimiter is escaped with a caret ("^").

Feed characters are converted:

  • Newline is converted to backslash concatenated with "n", resulting in "\n"
  • Form feed is converted to backslash concatenated with "f", resulting in "\f"

A newline separates each job from the next. Using newline as the delimiter leads to undefined behavior. 🚨 Don't do it, babe, it's not the vibe.

Example of getting output in delimiter-separated value format:

qstat -f -Fdsv

Job Id: 1.vbox|Job_Name = STDIN|Job_Owner =
root@vbox|job_state = Q|queue = workq|server =
vbox|Checkpoint = u|ctime = Fri Nov 11 17:57:05
2016|Error_Path = ...
  • -F json — prints output in JSON format (http://www.json.org/). Attribute output is preceded by timestamp, PBS version, and PBS server hostname. Example:
qstat -f F json

{
        "timestamp":1479277336,
        "pbs_version":"14.1",
        "pbs_server":"vbox",
        "Jobs":{
                "1.vbox":{
                        "Job_Name":"STDIN",
                        "Job_Owner":"root@vbox",
                        "job_state":"Q",
  • -G — shows size in gigabytes. Triggers alternate format. 💅
  • -M — shows size in megawords. A word is considered to be 8 bytes. Triggers alternate format. 🧚

🌟 Version Information 🌟

  • --version — the qstat command returns its PBS version information and exits. This option can only be used alone. No plus-ones allowed. 🙈

🌈 OPERANDS 🌈

🎀 Job Identifier Operands 🎀

The job ID is assigned by PBS at submission. Job IDs are used only with job status requests. Status information for the specified job(s) is displayed. Formats:

  • Job — <sequence number>[.<server>][@<server>]
  • Job array — <sequence number>[][.<server>][@<server>]
  • Subjob — <sequence number>[<index>][.<server>][@<server>]
  • Range of subjobs — <sequence number>[<start>-<end>][.<server>][@<server>]
💀 PSA from your girl: some shells require that you enclose a job array identifier in double quotes. The shell will absolutely eat it otherwise, fr fr.

🦋 Destination Operands 🦋

Name of queue, name of server, or name of queue at a specific server. Formats:

  • queue name — specifies name of queue for job or queue display.
    • When displaying job status, PBS displays status for all jobs in the specified queue at the default server.
    • When displaying queue status, PBS displays status for the specified queue at the default server.
  • queue name@server name — specifies name of queue at server for job or queue display.
    • When displaying job status, PBS displays status for all jobs in the specified queue at the specified server.
    • When displaying queue status, PBS displays status for the specified queue at the specified server.
  • @server name — specifies server name for job or queue display.
    • When displaying job status, PBS displays status for all jobs at all queues at the specified server.
    • When displaying queue status, PBS displays status for all queues at the specified server.
  • server name — specifies server name for server display.
    • When displaying server status (with the -B option) PBS displays status for the specified server.

💜 STANDARD ERROR 💜

The qstat command writes a diagnostic message to standard error for each error occurrence. So if something goes wrong, bestie, it'll tell you. Multiple times if you're really committed to the chaos. 😭

⭐ EXIT STATUS ⭐

  • Zero — upon successful processing of all operands. Slay! 🎉
  • Greater than zero — if any operands could not be processed. Not the vibe, but at least you know. 🫶

🌸 SEE ALSO 🌸

qalter(1B), qsub(1B), pbs_alterjob(3B), pbs_statjob(3B), pbs_statque(3B), pbs_statserver(3B), pbs_submit(3B), pbs_job_attributes(7B), pbs_queue_attributes(7B), pbs_server_attributes(7B), pbs_resources(7B) — the whole friend group right there, go say hi. 👯✨

And that's a wrap on qstat(1B), bestie! 🎀 This little masterpiece is filed under Local, dated 6 May 2020, and it's the qstat(1B) page you've been reading this whole time. Go forth and stat your heart out — you're literally so good at this. 💅🔥 periodt. 🌈

📦 where this page comes from