Introduction

The normal way to pause a Python script is time.sleep(seconds). It blocks the current thread for approximately the requested duration, which is exactly what you want in simple scripts. If the code is asynchronous or should remain responsive, use a different mechanism such as asyncio.sleep or an event-based wait.

Use time.sleep for a blocking delay

time.sleep is the direct answer for ordinary synchronous scripts.

1import time
2
3print("starting")
4time.sleep(2)
5print("two seconds later")

The argument can be an integer or a float, so short delays are fine too.

1import time
2
3time.sleep(0.25)
4print("quarter-second delay complete")

Understand that sleep blocks the current thread

While the thread is sleeping, that thread is not doing other work. In a command-line script, that is usually fine. In a GUI, server worker, or async program, it may be the wrong tool.

1import time
2
3for i in range(3):
4    print(f"step {i}")
5    time.sleep(1)

This pattern is simple and readable, but it pauses the thread completely between iterations.

Use asyncio.sleep in asynchronous code

If the code runs inside async def, use await asyncio.sleep(...) instead of time.sleep(...).

1import asyncio
2
3async def main():
4    print("before")
5    await asyncio.sleep(2)
6    print("after")
7
8asyncio.run(main())

This yields control back to the event loop so other asynchronous tasks can keep running.

Use an event wait when you may need early wake-up

Sometimes you want a delay that can also be interrupted. threading.Event().wait can be useful in threaded programs.

1import threading
2
3stop_event = threading.Event()
4
5# waits up to 5 seconds, but returns early if stop_event is set
6stop_event.wait(timeout=5)

This is often cleaner than time.sleep in worker threads that need a shutdown signal.

Do not use sleep as a synchronization hack

A common mistake is adding arbitrary delays to "wait until something is ready." That makes code flaky because the right delay depends on machine speed, network timing, and load. Prefer explicit signals, polling with a condition, or proper synchronization primitives.

For example, if you are waiting for a file, socket, or job to complete, checking readiness is better than guessing with sleep(1) in a loop.

Expect approximate timing, not exact scheduling

sleep guarantees at least roughly the delay requested, not perfect real-time precision. The actual wake-up time depends on operating system scheduling and process state. That is fine for script pacing and retries, but not for hard real-time timing guarantees.

Be explicit about seconds versus milliseconds

Python's sleep APIs use seconds, including fractional seconds. If you mean 250 milliseconds, pass 0.25, not 250.

import time

time.sleep(0.25)  # 250 milliseconds

That sounds obvious, but unit confusion is one of the most common causes of accidental long pauses in scripts.

Sleep is fine for pacing retries, but pair it with limits

Delays are often used in retry loops. If you do that, combine the sleep with a maximum retry count or timeout so the script cannot hang forever waiting on a failing dependency.

Common Pitfalls

• Using time.sleep inside asynchronous code instead of await asyncio.sleep.
• Treating sleep as a reliable way to synchronize with external events.
• Blocking a GUI or server thread with unnecessary delays.
• Assuming sleep wakes up at an exact millisecond boundary.
• Forgetting that the argument is in seconds, not milliseconds.

Summary

• Use time.sleep(seconds) for simple blocking delays.
• Use float values for sub-second pauses.
• Use asyncio.sleep in async code.
• Use event-based waiting when the delay may need cancellation.
• Prefer real synchronization over arbitrary sleep-based timing hacks.