os.sysconf

The Python side of the getconf command. Names are strings such as "SC_PAGE_SIZE", "CS_PATH" or "PC_NAME_MAX" (or the raw int values from the *_names dicts). An unknown string name raises ValueError; a known but unsupported one raises OSError with errno EINVAL. Unix only: none of these exist on Windows.

os functionPython 3.0+ (pathconf path-like 3.6+)
Common call
os.sysconf('SC_PAGE_SIZE')
Returns
int (or -1 if undefined)
Replaces
subprocess.run(["getconf", "PAGE_SIZE"])
Watch out
Unix only, and -1 means "no value", not an error
os.sysconf(namename — A name from sysconf_names / confstr_names / pathconf_names (e.g. "SC_CLK_TCK"), or its integer value.type: str | int · required, /) / os.confstr(name, /) / os.pathconf(path, name) / os.fpathconf(fd, namename — A name from sysconf_names / confstr_names / pathconf_names (e.g. "SC_CLK_TCK"), or its integer value.type: str | int · required, /)
→ int | str | None

Parameters

NameTypeRequiredDescription
namestr | intyesA name from sysconf_names / confstr_names / pathconf_names (e.g. "SC_CLK_TCK"), or its integer value.
pathstr | path-like | intyespathconf only: the file or directory to ask about (an open fd works too).
fdintyesfpathconf only: an open file descriptor; the same as pathconf(fd, name).

Return value

int | str | None — sysconf / pathconf / fpathconf: an int (-1 when the value is not defined). confstr: a str, or None when not defined.

Common patterns

Total physical memory (Linux)
Number of pages times the page size.
import os
total_bytes = os.sysconf('SC_PHYS_PAGES') * os.sysconf('SC_PAGE_SIZE')
Convert clock ticks to seconds
Fields in /proc/<pid>/stat are counted in SC_CLK_TCK ticks.
import os
seconds = utime_ticks / os.sysconf('SC_CLK_TCK')
Longest file name a directory allows
pathconf asks the file system that holds the path.
import os
max_name = os.pathconf('.', 'PC_NAME_MAX')
List what this system supports
The dicts map names to the integer values of this OS.
import os
sorted(n for n in os.sysconf_names if n.startswith('SC_NPROC'))

Examples

1. Unix only
import os hasattr(os, 'sysconf') == (os.name == 'posix')
Returns
True
2. Same family, same availability
import os len({hasattr(os, n) for n in ('sysconf', 'confstr', 'pathconf', 'fpathconf', 'sysconf_names')})
Returns
1
3. The page size is a power of two (portable via mmap)
import mmap p = mmap.PAGESIZE p > 0 and p & (p - 1) == 0
Returns
True
4. Pages times page size in GiB
pages, page_size = 2_000_000, 4096 pages * page_size / 2**30
Returns
7.62939453125
5. EINVAL: the errno for an unsupported name
import errno (errno.EINVAL, errno.errorcode[errno.EINVAL])
Returns
(22, 'EINVAL')

Pitfalls

1. Treating -1 as a real value
sysconf and pathconf return -1 for a limit the system does not define (there is no limit) instead of raising. Check before you compute with it.
use it directly
limit = -1  # what os.sysconf returns for an undefined limit
buffers = limit // 4096
buffers
-1
check for -1
limit = -1
buffers = None if limit < 0 else limit // 4096
buffers is None
True
2. Calling sysconf in cross-platform code
On Windows the functions do not exist at all. Guard with hasattr, or use a portable source such as mmap.PAGESIZE or os.cpu_count().
assume it exists
import os
os.name != 'posix' and hasattr(os, 'sysconf')  # never True: on Windows os.sysconf(...) raises AttributeError
False
portable page size
import mmap, os
page = os.sysconf('SC_PAGE_SIZE') if hasattr(os, 'sysconf') else mmap.PAGESIZE
page == mmap.PAGESIZE
True

When to use

Use it
  • Reading POSIX limits and configuration (page size, clock ticks, open-file limit, name length) on Unix
  • Translating /proc tick counts into seconds
Reach for something else
  • Page size in portable code → mmap.PAGESIZE
  • CPU count → os.cpu_count() / os.process_cpu_count()
  • Changing limits → resource.setrlimit (sysconf only reads)

Notes

CPython impl
Thin wrappers over the C functions sysconf(3), confstr(3), pathconf(3) and fpathconf(3); the *_names dicts are filled at build time from the constants the platform headers define
Availability
Unix only (sysconf, sysconf_names, confstr, confstr_names, pathconf, pathconf_names, fpathconf). Not available on Windows
Errors
Unknown string name: ValueError ("unrecognized configuration name" on Linux). Known name the system does not support: OSError with errno.EINVAL. Undefined value: -1 (sysconf / pathconf) or None (confstr)
Linux values
On our Linux test system (x86-64, glibc), SC_PAGE_SIZE equals mmap.PAGESIZE, SC_NPROCESSORS_ONLN equals os.cpu_count(), and SC_CLK_TCK is 100; check your own system
fpathconf
Since Python 3.3 fpathconf(fd, name) is the same as pathconf(fd, name); pathconf accepts path-like objects since 3.6

FAQ

sysconf, confstr, pathconf and fpathconf are Unix only (docs: Availability: Unix), and their results describe the machine running them. The examples show availability, the arithmetic you do with the results, and portable equivalents such as mmap.PAGESIZE.