os.nice

Niceness runs from -20 (most favoured) to 19 (least); 0 is the default. Raising it is always allowed, lowering it needs privileges, and the value is clamped at 19. Unix only (not WASI): Windows has priority classes instead (subprocess.BELOW_NORMAL_PRIORITY_CLASS and friends).

os functionPython 3.0+ (getpriority / setpriority / PRIO_* 3.3+)
Common call
os.nice(10)
Returns
the new niceness, e.g. 10
Replaces
starting the script with the nice / renice commands
Watch out
Higher niceness = LOWER priority; you cannot lower it back without privileges
os.nice(incrementincrement — nice only: added to the current niceness (negative needs privileges).type: int · required, /) / os.getpriority(which, who) / os.setpriority(which, whowho — A pid, process group id or uid; 0 means the calling process, its group, or its real user.type: int · required, prioritypriority — setpriority only: the absolute niceness, -20 to 19.type: int · required)
→ int

Parameters

NameTypeRequiredDescription
incrementintyesnice only: added to the current niceness (negative needs privileges).
whichintyesPRIO_PROCESS, PRIO_PGRP or PRIO_USER: what kind of id who is.
whointyesA pid, process group id or uid; 0 means the calling process, its group, or its real user.
priorityintyessetpriority only: the absolute niceness, -20 to 19.

Return value

int — nice: the new niceness. getpriority: the current niceness. setpriority: None.

Common patterns

Run a batch job in the background
Make yourself nicer at start-up so interactive work stays responsive.
import os
if hasattr(os, 'nice'):
    os.nice(10)
Lower the priority of a child only
Your own priority stays the same; Unix uses the nice command, Windows a creation flag.
import os, subprocess, sys
if sys.platform == 'win32':
    subprocess.run(['job'], creationflags=subprocess.BELOW_NORMAL_PRIORITY_CLASS)
else:
    subprocess.run(['nice', '-n', '10', 'job'])
Read and set another process
Absolute values with getpriority / setpriority.
import os
current = os.getpriority(os.PRIO_PROCESS, pid)
os.setpriority(os.PRIO_PROCESS, pid, min(19, current + 5))

Examples

1. Unix only
import os all(hasattr(os, n) == (os.name == 'posix') for n in ('nice', 'getpriority', 'setpriority', 'PRIO_PROCESS'))
Returns
True
2. Niceness range
lowest, highest = -20, 19 len(range(lowest, highest + 1))
Returns
40
3. nice() adds, setpriority() sets
current, increment = 5, 10 (current + increment, increment)
Returns
(15, 10)
4. The value is clamped at 19
current = 5 min(19, current + 25)
Returns
19
5. Windows has priority classes instead
import subprocess, sys hasattr(subprocess, 'BELOW_NORMAL_PRIORITY_CLASS') == (sys.platform == 'win32')
Returns
True

Pitfalls

1. Thinking a higher number means higher priority
Niceness is how nice you are to others: 19 gets the least CPU, -20 the most. Pick the most favoured process with min, not max.
max niceness
procs = {'backup': 19, 'web': 0, 'db': -5}
max(procs, key=procs.get)
'backup'
min niceness
procs = {'backup': 19, 'web': 0, 'db': -5}
min(procs, key=procs.get)
'db'
2. Passing an absolute value to nice()
nice(10) adds 10 to the current niceness; it does not set it to 10. Use setpriority for an absolute value. (On Linux, a process at niceness 5 that calls os.nice(10) ends at 15.)
treat as absolute
current = 5
increment = 10
expected = increment
expected == current + increment
False
it is relative
current = 5
increment = 10
min(19, current + increment)
15

When to use

Use it
  • Long batch jobs, builds, backups that should not slow down interactive work
  • Supervisors that adjust the priority of their workers
Reach for something else
  • Windows → subprocess creationflags=BELOW_NORMAL_PRIORITY_CLASS / IDLE_PRIORITY_CLASS, or psutil
  • Real-time scheduling → os.sched_setscheduler with SCHED_FIFO / SCHED_RR
  • I/O priority → the ionice command or psutil (os has no ionice)

Notes

CPython impl
nice wraps nice(2); getpriority / setpriority wrap the C functions of the same name. On Linux getpriority(PRIO_PROCESS, 0) returns the niceness itself (19 after os.nice(25) in our check)
Availability
Unix, not WASI (nice, getpriority, setpriority, PRIO_PROCESS, PRIO_PGRP, PRIO_USER). macOS adds PRIO_DARWIN_THREAD / PRIO_DARWIN_PROCESS / PRIO_DARWIN_BG / PRIO_DARWIN_NONUI (3.12+)
Permissions
Raising niceness is always allowed; lowering it (even back to the start value) raises PermissionError without privileges, as our Linux check confirmed
Linux values
PRIO_PROCESS == 0, PRIO_PGRP == 1, PRIO_USER == 2

FAQ

os.nice, getpriority, setpriority and the PRIO_* constants are Unix only (docs: Availability: Unix, not WASI), and nice() changes the priority of the whole process for good. The examples show the rules with plain numbers.