Python Reference ยท Standard Library: Concurrency, Network and Tools
The timeit module
Reference for Python's timeit module: timeit(), repeat(), autorange(), Timer, setup code, the command line interface and how to read benchmark results.
timeit measures how long a small piece of code takes. It runs the code many times with the garbage collector turned off and a high-resolution clock, so the figure is far more reliable than subtracting two time.time() calls around one execution.
Use it to compare two ways of doing the same small job, such as building a string with join() versus +=. For profiling a whole program to find where the time goes, use cProfile, not timeit.
import timeit seconds = timeit.timeit("sum(range(100))", number=10_000) print(seconds) # total time for 10,000 runs
Try it
Real timings differ on every machine and every run, so the examples do not print them. They print things that are always the same: how the functions are used, and results from a fake clock that moves a fixed step per reading.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
The times themselves are the whole point on your own machine, where a typical session looks like this (numbers are examples):
import timeit print(min(timeit.repeat("'-'.join(map(str, range(100)))", number=10_000, repeat=5))) # 0.37 (seconds for 10,000 runs; yours will differ)
From a shell: python -m timeit -s "data = list(range(1000))" "sum(data)" picks a run count automatically and prints something like 20000 loops, best of 5: 11.6 usec per loop.
Syntax
timeit.timeit(stmt='pass', setup='pass', timer=default_timer, number=1000000, globals=None) timeit.repeat(stmt='pass', setup='pass', timer=default_timer, repeat=5, number=1000000, globals=None) timeit.Timer(stmt, setup, timer, globals).autorange(callback=None)
| Name | Description |
|---|---|
stmt |
The code to time: a string of statements, or a callable with no arguments. |
setup |
Code run once before timing starts (imports, building test data). Same forms as stmt. |
timer |
A function returning the current time. The default is time.perf_counter. |
number |
How many times stmt runs in one measurement. |
repeat |
How many measurements repeat() makes. |
globals |
A dictionary of names available to stmt. Pass globals() or a small dict. |
Return value: timeit() returns the total seconds (a float) for all number runs, not the time per run. repeat() returns a list of such totals. Timer.autorange() returns (number, time_taken) after choosing number itself so that the run takes at least 0.2 seconds.
Usage notes
- Divide by
numberto get the time for one run. - Take the minimum of
repeat(), not the average. Slower readings come from other activity on the machine, not from your code. stmtruns in a fresh namespace. Names from your program are not visible unless you passglobals=(or usesetup="from __main__ import f"in older style, or a lambda).- Garbage collection is off during timing, which is unlike real programs. Re-enable it with
setup="gc.enable()"if memory churn matters. - Do not time setup work. Anything inside
stmtis repeated and counted, including building large inputs. - Mutating inputs bias results. Sorting an already sorted list in place on run 2 is a different job; make fresh data in each run or use
sorted()on a copy. - Micro-benchmarks mislead. A 5% win on a toy line rarely matters; measure the real hot path with a profiler before optimizing.
- Compare equal work. Check both versions return the same answer before comparing their speed.
- Command line:
python -m timeit -n 1000 -r 5 -s "setup" "stmt". - Timing a block once is better done with
time.perf_counter()before and after.
Related
time,functools,unittestsorted()- Lessons: Performance, Memory management