qalter(1B)

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

💅 qalter(1B) — alter PBS job, bestie edition 💅

PBS Professional's qalter(1B) manual page is here to help you tweak batch jobs. Think of it as the edit button for your job's attributes — but, like, with rules. ✨

🌸 NAME 🌸

qalter — alter PBS job.

✨ SYNOPSIS ✨

qalter [-a <date and time>] [-A <account string>]
       [-c <checkpoint spec>] [-e <error path>] [-h <hold list>] [-j
       <join>] [-k <discard>] [-l <resource list>] [-m <mail events>]
       [-M <user list>] [-N <name>] [-o <output path>] [-p <priority>]
       [-P <project>] [-r <y|n>] [-S <path list>] [-u <user list>] [-W
       <additional attributes>] <job ID> [<job ID> ...]

qalter --version

🦋 DESCRIPTION 🦋

The qalter command is used to alter one or more PBS batch jobs. Each of certain job attributes can be modified using the qalter option for that attribute. 💖

👑 Required Privilege 👑

A non-privileged user can alter their own jobs, whether they are queued or running. An Operator or Manager can alter any job, whether it is queued or running.

A non-privileged user can only lower resource requests. A Manager or Operator can raise or lower resource requests.

🔥 Modifying resources and job placement 🔥

A Manager or Operator may lower or raise requested resource limits, except for per-process limits such as pcput and pmem, because these are set when the process starts, and enforced by the kernel. A non-privileged user can only lower resource requests.

The qalter command cannot be used by a non-privileged user to alter a custom resource which has been created to be invisible or read-only for users.

If a job is running, the only resources that can be modified are mppnodes, mppt, cput, walltime, min_walltime, and max_walltime.

If a job is queued, any resource mentioned in the options to the qalter command can be modified, but requested modifications must fit within the limits set at the server and queue for the amount of each resource allocated for queued jobs. If a requested modification does not fit within these limits, the modification is rejected. 🚫

A job's resource request must fit within the queue's and server's resource run limits. If a modification to a resource exceeds the amount of the resource allowed by the queue or server to be used by running jobs, the job is never run. 😭

Requesting resources includes setting limits on resource usage and controlling how the job is placed on vnodes.

🧚 Syntax for Modifying Resources and Job Placement 🧚

Resources are modified by using the -l option, either in chunks inside of selection statements, or in job-wide requests using <resource name>=<value> pairs. The selection statement is of the form:

-l select=[<N>:]<chunk>[+[<N>:]<chunk> ...]

where N specifies how many of that chunk, and a chunk is of the form:

<resource name>=<value>[:<resource name>=<value> ...]

Job-wide <resource name>=<value> requests are of the form:

-l <resource name>=<value>[,<resource name>=<value> ...]

🎀 The Place Statement 🎀

You choose how your chunks are placed using the place statement. The place statement can contain the following elements, in any order:

-l place=[<arrangement>][:<sharing>][:<grouping>]

where

  • arrangement — Whether this chunk is willing to share this vnode or host with other chunks from the same job. One of free | pack | scatter | vscatter.
    • free — Place job on any vnodes.
    • pack — All chunks are taken from one host.
    • scatter — Only one chunk with any MPI processes is taken from a host. A chunk with no MPI processes may be taken from the same vnode as another chunk.
    • vscatter — Only one chunk is taken from any vnode. Each chunk must fit on a vnode.
  • sharing — Whether this chunk is willing to share this vnode or host with other jobs. One of excl | shared | exclhost.
    • excl — Only this job uses the vnodes chosen.
    • shared — This job can share the vnodes chosen.
    • exclhost — The entire host is allocated to the job.
  • grouping — Whether the chunks from this job should be placed on vnodes that all have the same value for a resource. Can have only one instance of group=<resource name>.
    • group=<resource name> — Chunks are grouped according to a resource. All vnodes in the group must have a common value for resource, which can be either the built-in resource host or a custom vnode-level resource. The resource name must be a string or a string array.

The place statement cannot begin with a colon. Colons are delimiters; use them only to separate parts of a place statement, unless they are quoted inside resource values.

For more on resource requests, usage limits and job placement, see pbs_resources(7B).

🌈 Modifying Attributes 🌈

The user alters job attributes via options to the qalter command. Each qalter option changes a job attribute. See pbs_job_attributes(7B).

The behavior of the qalter command may be affected by any site hooks. Site hooks can modify the job's attributes, change its routing, etc. 🌀

To modify the max_run_subjobs attribute, use qalter -Wmax_run_subjobs=<new value> <job ID>.

💀 Caveats and Restrictions for Altering Jobs 💀

When you lengthen the walltime of a running job, make sure that the new walltime will not interfere with any existing reservations etc.

⚠️ If any of the modifications to a job fails, none of the job's attributes is modified.

A job that is in the process of provisioning cannot be altered.

🍓 OPTIONS 🍓

  • -a <date and time> — Changes the point in time after which the job is eligible for execution. Given in pairs of digits. Sets job's Execution_Time attribute to date and time. Format: [[[[CC]YY]MM]DD]hhmm[.SS]

where CC is the century, YY is the year, MM is the month, DD is the day of the month, hh is the hour, mm is the minute, and SS is the seconds.

Each portion of the date defaults to the current date, as long as the next-smaller portion is in the future. For example, if today is the 3rd of the month and the specified day DD is the 5th, the month MM is set to the current month.

If a specified portion has already passed, the next-larger portion is set to one after the current date. For example, if the day DD is not specified, but the hour hh is specified to be 10:00 a.m. and the current time is 11:00 a.m., the day DD is set to tomorrow.

The job's Execution_Time attribute can be altered after the job has begun execution, in which case it will not take effect until the job is rerun.

  • -A <account string> — Replaces the accounting string associated with the job. Used for labeling accounting data. Sets job's Account_Name attribute to account string. This attribute cannot be altered once the job has begun execution.

Format: String

  • -c <checkpoint spec> — Changes when the job will be checkpointed. Sets job's Checkpoint attribute. An $action script is required to checkpoint the job. See the pbs_mom(8B) man page. This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

The argument checkpoint spec can take one of the following values:

  • c — Checkpoint at intervals, measured in CPU time, set on job's execution queue. If no interval set at queue, job is not checkpointed.
  • c=<minutes of CPU time> — Checkpoint at intervals of specified number of minutes of job CPU time. This value must be greater than zero. If interval specified is less that that set on job's execution queue, queue's interval is used. Format: Integer
  • w — Checkpoint at intervals, measured in walltime, set on job's execution queue. If no interval set at queue, job is not checkpointed.
  • w=<minutes of walltime> — Checkpoint at intervals of the specified number of minutes of job walltime. This value must be greater than zero. If the interval specified is less than that set on the job's execution queue, the queue's interval is used. Format: Integer
  • n — No checkpointing.
  • s — Checkpoint only when the server is shut down.
  • u — Unset. Defaults to behavior when interval argument is set to s.

Default: u Format: String

  • -e <error path> — Replaces the path to be used for the job's standard error stream. Sets job's Error_Path attribute to error path. Overridden by -k option. Format: [<hostname>:]<path>

The error path is interpreted as follows:

  • path — If path is relative, it is taken to be relative to the current working directory of the qalter command, where it is executing on the current host.

If path is absolute, then it is taken to be an absolute path on the current host where the qalter command is executing.

  • hostname:path — If path is relative, it is taken to be relative to the user's home directory on the host named hostname.

If path is absolute, it is the absolute path on the host named hostname.

If path does not include a filename, the default filename is <job ID>.ER.

If the -e option is not specified, PBS writes standard error to the default filename, which has this form: <job name>.e<sequence number>.

This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

If you use a UNC path, the hostname is optional. If you use a non-UNC path, the hostname is required.

  • -h <hold list> — Updates the job's hold list. Adds hold list to the job's Hold_Types attribute. The hold list is a string of one or more characters. The following table shows the holds and the privilege required to set each:

Hold — Meaning — Who Can Set

  • u — Meaning: User — Who can set: Job owner, Operator, Manager, administrator, root

okay so the rest of that access table is giving:

  • o — Other — Operator, Manager, administrator, root
  • s — System — Manager, administrator, root, PBS (dependency)
  • n — None — Job owner, Operator, Manager, administrator, root
  • p — Bad password — Administrator, root

This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

  • -j <join> — Changes whether and how to join the job's standard error and standard output streams. Sets the job's Join_Path attribute to join. 💅

This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

The join argument can take the following values:

  • oe — Standard error and standard output are merged into standard output.
  • eo — Standard error and standard output are merged into standard error.
  • n — Standard error and standard output are not merged.

Default: n; not merged

  • -k <discard> — Changes whether and which of the standard output and standard error streams is left behind on the execution host, and whether they are written to their final destinations. Sets the job's Keep_Files attribute to discard. 🎀
This attribute cannot be altered once the job has begun execution. no cap, lock it in before it starts.

In the case where output and/or error is retained on the execution host in a job-specific staging and execution directory created by PBS, these files are deleted when PBS deletes the directory.

Default: n; neither is retained, and files are not written to final destinations

The discard argument can take the following values:

  • e — The standard error stream is retained on the execution host, in the job's staging and execution directory. The filename is: <job name>.e<sequence number>
  • o — The standard output stream is retained on the execution host, in the job's staging and execution directory. The filename is: <job name>.o<sequence number>
  • eo, oe — Both standard output and standard error streams are retained on the execution host, in the job's staging and execution directory.
  • d — Output and/or error are written directly to their final destination. Overrides the action of leaving files behind on the execution host.
  • n — Neither stream is retained.
  • -l <resource list> — Allows the user to change requested resources and job placement. Sets job's Resource_list attribute to resource list. Uses resource request syntax. Requesting a resource places a limit on its usage. Users without manager or operator privilege cannot alter a custom resource which was created to be invisible or read-only for users. ✨

For syntax, see Syntax for Modifying Resources and Job Placement above.

If a requested modification to a resource would exceed the server's or job queue's limits, the resource request is rejected. Which resources can be altered is system-dependent.

If the job was submitted with an explicit -l select=, vnode-level resources must be qaltered using the -l select= form. In this case a vnode level resource <resource> cannot be qaltered with the -l <resource name> form.

The place statement cannot begin with a colon. periodt.

For example:

Submit the job:
% qsub -l select=1:ncpus=2:mem=512mb jobscript
Job's ID is 230

qalter the job using "-l <resource name>" form:
% qalter -l ncpus=4 230

Error reported by qalter:
qalter: Resource must only appear in "select"
specification when select is used: ncpus 230

qalter the job using the "-l select=" form:
% qalter -l select=1:ncpus=4:mem=512mb 230

No error reported by qalter:
%

For more on resource requests, usage limits and job placement, see pbs_resources(7B).

  • -m <mail events> — Changes the set of conditions under which mail about the job is sent. Sets job's Mail_Points attribute to mail events. The mail events argument can be one of the following: the single character n; any combination of a, b, and e, with optional j. 📬

The following table lists the sub-options to the -m option:

  • n — No mail is sent
  • a — Mail is sent when the job is aborted by the batch system
  • b — Mail is sent when the job begins execution
  • e — Mail is sent when the job terminates
  • j — Mail is sent for subjobs. Must be combined with one or more of the a, b, or e sub-options

Can be used with job arrays but not subjobs.

Format: String Syntax: n | [j](one or more of a, b, e) Example: -m ja Default: a

  • -M <user list> — Alters list of users to whom mail about the job is sent. Sets job's Mail_Users attribute to user list. 💌

Format:

<username>[@<hostname>][,<username>[@<hostname>],...]

Default: job owner

  • -N <name> — Renames the job. Sets job's Job_Name attribute to name. 🏷️

Format: Job Name Default: if a script is used to submit the job, the job's name is the name of the script. If no script is used, the job's name is STDIN.

  • -o <output path> — Alters path to be used for the job's standard output stream. Sets job's Output_Path attribute to output path. Overridden by -k option.

Format:

[<hostname>:]<path>

The output path is interpreted as follows:

  • path — If path is relative, it is taken to be relative to the current working directory of the command, where it is executing on the current host.

If path is absolute, it is taken to be an absolute path on the current host where the command is executing.

  • hostname:path — If path is relative, it is taken to be relative to the user's home directory on the host named hostname.

If path is absolute, it is the absolute path on the host named hostname.

If path does not include a filename, the default filename is <job ID>.OU

If the -o option is not specified, PBS writes standard output to the default filename, which has this form: <job name>.o<sequence_number>

This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

If you use a UNC path, the hostname is optional. If you use a non-UNC path, the hostname is required.

  • -p <priority> — Alters priority of the job. Sets job's Priority attribute to priority. 🔥

This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

Format: Host-dependent integer Range: [-1024, +1023] inclusive Default: Zero

  • -P <project> — Specifies a project for the job. Sets job's project attribute to specified value. 📁

Format: Project Name Default: _pbs_project_default

  • -r <y|n> — Changes whether the job is rerunnable. Sets job's Rerunable attribute to the argument. Does not affect how the job is handled when the job is unable to begin execution. See the qrerun(1B) command. 🔁

Format: Single character, y or n

  • y — Job is rerunnable.
  • n — Job is not rerunnable.

Default: y

Interactive jobs are not rerunnable. Job arrays are always rerunnable.

  • R <remove options> — Changes whether standard output and/or standard error files are automatically removed upon job completion. Sets job's Remove_Files attribute to remove options. Overrides default path names for these streams. Overrides -o and -e options. 🗑️
This attribute cannot be altered once the job has begun execution.

Default: Unset; neither is removed

The remove options argument can take the following values:

  • e — The standard error stream is removed (deleted) upon job completion
  • o — The standard output stream is removed (deleted) upon job completion
  • eo, oe — Both standard error and standard output streams are removed (deleted) upon job completion
  • unset — Neither stream is removed
  • -S <path list> — Specifies the interpreter or shell path for the job script. Sets job's Shell_Path_List attribute to path list. 🐚

The path_list argument is the full path to the interpreter or shell including the executable name.

Only one path may be specified without a hostname. Only one path may be specified per named host. The path selected is the one whose hostname is that of the server on which the job resides.

This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

Format:

<path>[@<hostname>][,<path>@<hostname> ...]

If the path contains spaces, it must be quoted, for example:

qsub -S "C:Program Files\PBS Pro\bin\pbs_python.exe"
<script name>

Default: User's login shell on execution node

Example of using bash via a directive:

#PBS -S /bin/bash@mars,/usr/bin/bash@jupiter

Example of using a Python script from the command line on Linux:

qsub -S $PBS_EXEC/bin/pbs_python <script name>

Example of using a Python script from the command line on Windows:

qsub -S PBS_EXEC\bin\pbs_python.exe <script name>
  • -u <user list> — changes the whole list of usernames the job can run as, and sets the job's User_List attribute. 💜

Only one username may be specified without a hostname. Only one username may be specified per named host. When the server picks, it goes in this order: first the username whose hostname matches the server name, and if that doesn't exist, the username with no hostname specified. The usernames on the server and the execution hosts have to be the same, and the job owner needs authorization to run as the specified user. 🔑

This attribute cannot be altered once the job has begun execution — so like, decide early, bestie. 😭

Format:

   <username>[@<hostname>][,<username>@<hostname> ...]

Default: job owner (the username on the submit host).

  • -W <additional attributes> — each sub-option under -W lets you change one specific job attribute. 🎀

Format:

   -W <attribute name>=<value>[,<attribute name>=<value>...]

If white space occurs inside the additional attributes argument, or the equal sign = occurs inside an attribute value string, you gotta wrap that argument or string in single or double quotes. 💅

PBS supports these attributes via the -W option:

depend=<dependency list>

Defines dependencies between this job and other jobs. Sets the job's depend attribute to the dependency list. That list has the form:

<type>:<arg list>[,<type>:<arg list> ...]

where, except for the on type, the arg list is one or more PBS job IDs in the form:

<job ID>[:<job ID> ...]

The types and their argument lists can be:

  • after: <arg list> — this job may be scheduled for execution at any point after all jobs in arg list have started execution. 🏁
  • afterok: <arg list> — this job may be scheduled for execution only after all jobs in arg list have terminated with no errors. See "Warning about exit status with csh" in EXIT STATUS. ✨
  • afternotok: <arg list> — this job may be scheduled for execution only after all jobs in arg list have terminated with errors. See "Warning about exit status with csh" in EXIT STATUS. 💀
  • afterany: <arg list> — this job may be scheduled for execution after all jobs in arg list have finished execution, with any exit status (with or without errors). Heads up: this job will not run if a job in the arg list was deleted without ever having been run. 🙈
  • before: <arg list> — jobs in arg list may begin execution once this job has begun execution.
  • beforeok: <arg list> — jobs in arg list may begin execution once this job terminates without errors. See "Warning about exit status with csh" in EXIT STATUS. 🦋
  • beforenotok: <arg list> — if this job terminates execution with errors, jobs in arg list may begin. See "Warning about exit status with csh" in EXIT STATUS. 😭
  • beforeany: <arg list> — jobs in arg list may begin execution once this job terminates execution, with or without errors.
  • on: count — this job may be scheduled for execution after count dependencies on other jobs have been satisfied. This type is used in conjunction with one of the before types listed above. count is an integer greater than 0. 🔢

Restrictions — job IDs in the arg list of before types must have been submitted with a type of on.

To use the before types, the user must have the authority to alter the jobs in arg list. Otherwise the dependency is rejected and the new job is aborted. 🚨

Error processing of the existence, state, or condition of the job on which the newly submitted job depends happens after the job is queued. If an error is detected, the new job is deleted by the server, and mail is sent to the job submitter stating the error. 📬

Dependency examples:

qalter -W depend=afterok:123.host1.domain.com /tmp/script
qalter -W depend=before:234.host1.com:235.host1.com /tmp/script

group_list=<group list>

Alters the list of group names; the job will run under a group name from this list. Sets the job's group_List attribute to group list. 🌸

Only one group name may be specified without a hostname. Only one group name may be specified per named host. The server on which the job resides selects first the group name whose hostname is the same as the server name; failing that, the next selection is the group name with no specified hostname. The group names on the server and the execution hosts must be the same. 🫶

Format:

   <group>[@<hostname>][,<group>@<hostname> ...]

Default: no default.

release_nodes_on_stageout=<value>

When set to True, all of the job's vnodes that are not on the primary execution host are released when stageout begins. 💅

Cannot be used with vnodes tied to Cray X* series systems.

When cgroups is enabled and this is used with some but not all vnodes from one MoM, resources on those vnodes that are part of a cgroup are not released until the entire cgroup is released. 😬

The job's stageout attribute must be set for the release_nodes_on_stageout attribute to take effect.

Format: Boolean Default: False

run_count=<count>

Sets the number of times the server thinks it has run the job. Sets the job's run_count attribute to count. 🔁

Can be set while the job is running.

Job is held when the value of this attribute goes over 20. ⚠️

Format: integer greater than or equal to zero

sandbox=<sandbox spec>

Changes which directory PBS uses for the job's staging and execution. Sets the job's sandbox attribute to the value of sandbox spec. 📁

Format: String

Allowed values for sandbox spec:

  • PRIVATE — PBS creates a job-specific directory for staging and execution.
  • HOME or unset — PBS uses the user's home directory for staging and execution.

stagein=<path list>

stageout=<path list>

Changes files or directories to be staged in before execution, or staged out after execution is complete. Sets the job's stagein and stageout attributes to the specified path lists. On completion of the job, all staged-in and staged-out files and directories are removed from the execution host(s). 🧹

A path list has the form:

   <filespec>[,<filespec>]

where filespec is

   <execution path>@<hostname>:<storage path>

regardless of the direction of the copy. The execution path is the name of the file or directory on the primary execution host. It can be relative to the staging and execution directory on the execution host, or it can be an absolute path. 🛤️

The @ character separates the execution path from the storage path.

The storage path is the path on hostname. The name can be relative to the staging and execution directory on the primary execution host, or it can be an absolute path.

If the path list has more than one filespec — i.e. it contains commas — it must be enclosed in double quotes. 🎀

If you use a UNC path, the hostname is optional. If you use a non-UNC path, the hostname is required.

umask=<value>

Alters the umask with which the job is started. Controls the umask of the job's standard output and standard error. Sets the job's umask attribute to value. 🎭

Format: one to four digits; typically two Default: 077

The following example allows group and world read of the job's output and error:

   -W umask=33
  • --version — qalter returns its PBS version information and exits. This option can only be used alone. 👑

✨ OPERANDS ✨

The qalter command accepts a job ID list as its operand. The job ID list is a space-separated list of one or more job IDs, for normal jobs or array jobs. 💖

Subjobs and ranges of subjobs are not alterable. 🚫

Job IDs have the form:

   <sequence number>[.<server name>][@<server name>]
   <sequence number>[][.<server name>][@<server name>]
Ngl, some shells require that you enclose a job array ID in double quotes. Just a lil heads up. 🙈

😭 STANDARD ERROR 😭

The qalter command writes a diagnostic message to standard error for each error occurrence.

🌈 EXIT STATUS 🌈

  • Zero — upon successful processing of input ✅
  • Greater than zero — upon failure 💀

Warning about exit status with csh

If a job is run in csh and a .logout file exists in the home directory in which the job executes, the exit status of the job is that of the .logout script — not the job script. And like… this may impact any inter-job dependencies. 😬 Fr fr, watch out for that one.

🦋 SEE ALSO 🦋

pbs_job_attributes(7B), pbs_resources(7B), qdel(1B), qhold(1B), qmove(1B), qmsg(1B), qrerun(1B), qrls(1B), qselect(1B), qstat(1B), qsub(1B)

K that's the whole page, bestie — you're officially a qalter girlie now. 💅✨ This one's the Local flavor, dated 25 January 2021, and it's qalter(1B) all the way down. Go forth and alter responsibly 🫶🎀

📦 where this page comes from