Benchmarking with timeit

The timeit module measures how long small snippets of code take by running them many times, giving you reliable numbers instead of the noisy guesses a single timer produces.

Learn Benchmarking with timeit in our free Python course — an interactive lesson with runnable examples, a practice exercise and a quick reference.

Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

When you want to know which of two approaches is actually faster, timeit is the right tool — it handles the warm-up, repetition, and timing details so your comparison is trustworthy.

timeit.timeit(stmt, setup, number) runs stmt number times and returns the total seconds. The setup code runs once before timing — use it to import modules or build test data that shouldn't count toward the measurement:

The real point of timeit is to settle "which is faster?" arguments. Time both candidates with the same number , then compare the totals. A classic example: testing membership in a list vs a set :

timeit.repeat runs the whole timing several times and returns a list. The official advice is to take the minimum , not the average — the fastest run is the one least disturbed by background processes:

The %timeit "magic" picks a sensible number and repeat for you and prints a nicely formatted result — it's timeit with zero boilerplate.

Fill in each ___ to benchmark two lookups and print the winner. (Hint: the function is timeit , and the keyword for run count is number .)

❌ Referencing your own variables inside a string stmt

❌ Comparing absolute times across machines or runs

❌ Forgetting the default number is one million

Benchmark summing with a generator expression vs building a throwaway list first, run each five times with repeat , take the minimum of each, and print which approach wins. (Surprise: for a modest size the list version often edges it out, because the generator pays a small overhead per item — exactly the kind of myth-busting timeit is built for.)

Lesson complete — you benchmark like a pro!

You can time snippets with timeit.timeit , prepare data in setup , compare two approaches by their relative result, run several timings with repeat and take the minimum, and reach for %timeit in notebooks — never trusting a single manual time() reading again.

🚀 Up next: the warnings module — signal problems without crashing, and control how they're shown.

Practice quiz

What is the timeit module used for?

  • Scheduling functions to run at a future time
  • Adding timeouts to long-running functions
  • Accurately measuring how long small code snippets take to run
  • Logging timestamps to a file

Answer: Accurately measuring how long small code snippets take to run. timeit runs a snippet many times and reports a stable per-run figure, making it the standard tool for microbenchmarks.

In timeit.timeit(stmt, setup, number), what does the setup code do?

  • Runs once before timing and is NOT counted in the measurement
  • Runs on every repetition and is counted in the time
  • Replaces the statement being timed
  • Cleans up after the timing finishes

Answer: Runs once before timing and is NOT counted in the measurement. setup runs a single time before timing begins — use it to import modules or build test data that should not count toward the measured time.

What does the number argument control?

  • How many seconds to run for
  • How many CPU cores to use
  • How many decimal places to print
  • How many times the stmt runs in a single timing

Answer: How many times the stmt runs in a single timing. number is the count of executions in one timing (default 1,000,000). The total time is spread across those runs to smooth out noise.

What is the default value of number if you do not specify it?

  • 1
  • 1,000,000
  • 1,000
  • 100

Answer: 1,000,000. The default number is one million, which is why forgetting it on a slow snippet (like time.sleep) makes timeit appear to hang.

timeit.repeat returns a list of timings. Which summary does the official advice recommend?

  • The minimum
  • The average (mean)
  • The maximum
  • The median

Answer: The minimum. Take the minimum — the fastest run is the one least disturbed by background processes, so it best reflects the code's true speed.

Why should you report relative results (a winner or ratio) instead of absolute times?

  • Absolute times are always wrong
  • timeit cannot produce absolute times
  • Absolute times depend on CPU, OS, and load, so they vary across machines and runs
  • Relative results run faster to compute

Answer: Absolute times depend on CPU, OS, and load, so they vary across machines and runs. Raw times vary by machine and current load, but which approach is faster (the relative result) stays valid everywhere.

Why does this fail: timeit.timeit('sum(data)', number=1000) where data is your own variable?

  • sum() is not allowed in timeit
  • The stmt runs in its own namespace, so 'data' is not defined — NameError
  • number must be at least 1,000,000
  • Strings cannot be timed

Answer: The stmt runs in its own namespace, so 'data' is not defined — NameError. The string statement has its own namespace. Build the data in setup (e.g. setup='data = list(range(100))') so the name exists during timing.

Which membership test does timeit reliably show to be faster, regardless of machine?

  • Membership in a list (linear scan)
  • Both are exactly equal
  • It changes randomly every run
  • Membership in a set (hashing, ~constant time)

Answer: Membership in a set (hashing, ~constant time). A set uses hashing for roughly constant-time membership, while a list scans element by element, so set membership wins this benchmark every time.

What does %timeit do in a Jupyter / IPython notebook?

  • Times every cell in the notebook at once
  • Times a single line, auto-picking sensible number and repeat values
  • Permanently slows the kernel for accuracy
  • Installs the timeit module

Answer: Times a single line, auto-picking sensible number and repeat values. The %timeit magic times one line and chooses good number/repeat settings for you; %%timeit times a whole cell — it's timeit with zero boilerplate.

Besides a code string, what else can timeit.timeit accept as the thing to time?

  • A file path
  • A list of numbers
  • A callable (a function object)
  • A regular expression

Answer: A callable (a function object). You can pass a callable directly, e.g. timeit.timeit(build_list, number=1000), instead of a string of code.