Runner CLI¶
Command line options of the Runner class.
Loop iterations¶
Options:
--rigorous
--fast
-p PROCESSES/--processes=PROCESSES
-n VALUES/--values=VALUES
-l LOOPS/--loops=LOOPS
-w WARMUPS/--warmups=WARMUPS
--min-time=MIN_TIME
Default without JIT (ex: CPython): 20 processes, 3 values per process (total: 60 values), and 1 warmup.
Default with a JIT (ex: PyPy): 6 processes, 10 values per process (total: 60 values), and 10 warmups.
--rigorous: Spend longer running tests to get more accurate results. Multiply the number ofPROCESSESby 2. Default: 40 processes and 3 values per process (120 values).--fast: Get rough answers quickly. Divide the number ofPROCESSESby 2 and multiply the number ofVALUESby 2/3 (0.6). Default: 10 processes and 2 values per process (total: 20 values).PROCESSES: number of processes used to run the benchmark (default:20, or6with a JIT)VALUES: number of values per process (default:3, or10with a JIT)WARMUPS: the number of ignored values used to warmup to benchmark (default:1, or10with a JIT)LOOPS: number of loops per value.x^ysyntax is accepted, example:--loops=2^8uses256iterations. By default, the timer is calibrated to get raw values taking at leastMIN_TIMEseconds.MIN_TIME: Minimum duration of a single raw value in seconds (default:100 ms)
The Runs, values, warmups, outer and inner loops section explains the purpose of these parameters and how to configure them.
Output options¶
Options:
-d/--dump
-m/--metadata
-g/--hist
-t/--stats
-v/--verbose
-q/--quiet
--dumpdisplays the benchmark run results, see pyperf dump command--metadatadisplays metadata: see pyperf show metadata command--histrenders an histogram of values, see pyperf hist command--statsdisplays statistics (min, max, …), see pyperf stats command--verboseenables the verbose mode--quietenables the quiet mode
JSON output¶
Options:
-o FILENAME/--output=FILENAME
--append=FILENAME
--pipe=FD
--output=FILENAMEwrites the benchmark result as JSON into FILENAME--append=FILENAMEappends the benchmark runs to benchmarks of the JSON file FILENAME. The file is created if it doesn’t exist.--pipe=FDwrites benchmarks encoded as JSON into the pipe FD.
Misc¶
Option:
-h/--help
--python=PYTHON
--compare-to REF_PYTHON
--python-names REF_NAME:CHANGED_NAME
--affinity=CPU_LIST
--inherit-environ=VARS
--copy-env
--no-locale
--timeout TIMEOUT
--track-memory
--tracemalloc
--in-process
--python=PYTHON: Python executable. By default, use the running Python (sys.executable). The Python executable must have thepyperfmodule installed.--compare-to=REF_PYTHON: Run benchmark on the Python executableREF_PYTHON, run benchmark on Python executablePYTHON, and then compareREF_PYTHONresult toPYTHONresult.--python-names=REF_NAME:CHANGED_NAME: Option used with--compare-toto namePYTHONasCHANGED_NAMEand nameREF_PYTHONasREF_NAMEin results. For example,./python ... --compare-to=../ref/python --python-names=ref:patchuses “ref” name for../ref/pythonand use “patch” name for./python.--affinity=CPU_LIST: Specify CPU affinity for worker processes. This way, benchmarks can be forced to run on a given set of CPUs to minimize run to run variation. By default, worker processes are pinned to isolate CPUs if isolated CPUs are found. See CPU pinning and CPU isolation.--inherit-environ=VARS:VARSis a comma-separated list of environment variable names which are inherited by worker child processes. By default, only the following variables are inherited:PATH,PYTHONPATH,HOME,TEMP,COMSPEC,SystemRoot,SystemDrive, and locale environment variables. See the--no-localebelow for locale environment variables.--copy-env: Inherit all environment variables.--no-locale: Don’t inherit locale environment variables:LANGLC_ADDRESSLC_ALLLC_COLLATELC_CTYPELC_IDENTIFICATIONLC_MEASUREMENTLC_MESSAGESLC_MONETARYLC_NAMELC_NUMERICLC_PAPERLC_TELEPHONELC_TIME
--timeout: set a timeout in seconds for an execution of the benchmark. If the benchmark execution times out, pyperf exits with error code 124. There is no time out by default.--tracemalloc: Use thetracemallocmodule to track Python memory allocation and get the peak of memory usage in metadata (tracemalloc_peak). See the tracemalloc module.--track-memory: get the memory peak usage. it is less accurate thantracemalloc, but has a lower overhead. On Linux, compute the sum ofPrivate_CleanandPrivate_Dirtymemory mappings of/proc/self/smaps. On Windows, getPeakPagefileUsageofGetProcessMemoryInfo()(of the current process): the peak value of the Commit Charge during the lifetime of this process.--in-process: run the benchmark in the current process instead of a child process. This is useful when you cannot spawn child processes, such as on WASM environments. Note that this makes each run affect the next run, as the benchmark is executed in the same process.
Internal usage only¶
The following options are used internally by pyperf and should not be used explicitly:
--worker
--worker-task=TASK_ID
--calibrate-loops
--recalibrate-loops
--calibrate-warmups
--recalibrate-warmups
--debug-single-value
--worker: a worker process, run the benchmark in the running process--worker-task: Identifier of the worker task, only execute the benchmark function numberTASK_ID.--calibrate-loops: calibrate the number of loops--recalibrate-loops: recalibrate the number of loops. Option used with JIT compilers to validate the number of loops.--calibrate-warmups: calibrate the number of warmups--recalibrate-warmups: recalibrate the number of warmups--debug-single-value: Debug mode, only produce a single value