Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Concurrency, Network and Tools

The threading module

Reference for Python's threading module: Thread, Lock, RLock, Event, Semaphore, Condition, Timer, thread-local data, the GIL and when to use threads.

The threading module runs several flows of control inside one process. Each thread has its own call stack but shares memory with the others, so threads can work on the same data. That makes them a good fit for I/O-bound jobs: while one thread waits for a network reply, a disk read or a database, another one can run.

In the standard CPython build, the global interpreter lock (GIL) lets only one thread execute Python bytecode at a time, so threads do not speed up pure number-crunching. For CPU-bound work use multiprocessing or concurrent.futures.ProcessPoolExecutor. Python 3.13 added an optional free-threaded build without the GIL, but code should still protect shared data with locks.

Python
import threading

t = threading.Thread(target=print, args=("hello from a thread",))
t.start()
t.join()

The in-browser runner cannot start real threads: Thread.start() raises RuntimeError: can't start new thread. The examples below run here (locks, events and other primitives work, they just have nothing to contend with); code that starts threads is shown read-only.

Try it

Python What works in the browser: primitives and thread info

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.

Python A Thread subclass (calling run() directly as a stand-in)

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 same program in a normal Python environment (read-only, do not expect it to run in the browser):

Python
for w in workers:
    w.start()
for w in workers:
    w.join()
print(shared["total"])   # 4000, because every increment held the lock

What is in the module

Name Description
Thread(target=None, args=(), kwargs=None, *, name=None, daemon=None) A thread of execution. start() begins it, join(timeout=None) waits for it, is_alive() checks it.
Lock() Mutual exclusion. acquire(blocking=True, timeout=-1), release(), and with lock:.
RLock() Re-entrant lock: the owning thread can acquire it several times.
Event() A flag with set(), clear(), is_set() and wait(timeout=None).
Condition(lock=None) Wait for a condition to become true with wait(), notify() and notify_all().
Semaphore(value=1), BoundedSemaphore Limit how many threads use a resource at once.
Barrier(parties) Makes a group of threads wait until all of them arrive.
Timer(interval, function) A thread that runs function after a delay; cancel() stops it.
local() Object whose attributes are separate for each thread.
current_thread(), main_thread(), enumerate(), active_count(), get_ident() Inspect running threads.
excepthook, settrace, setprofile, stack_size() Hooks and tuning.

Thread.start() raises RuntimeError if called twice or if the system cannot create a thread. Lock.release() raises RuntimeError if the lock is not held.

Usage notes

  • Always join() or make the thread a daemon. The interpreter waits for non-daemon threads at exit; daemon threads (daemon=True) are stopped abruptly and may leave work half-done.
  • Call target, not target(). Thread(target=work()) runs work immediately in the current thread and passes its result.
  • A single-element tuple needs a comma: args=(5,), not args=(5).
  • The GIL does not make your code thread-safe. counter += 1 is several steps; two threads can interleave and lose updates. Protect compound operations with a Lock.
  • Use with lock: so the lock is released even when an error occurs.
  • Exceptions in a thread do not reach the caller. They are printed (via threading.excepthook) and the thread ends. Catch errors in the target, or use concurrent.futures, whose futures carry exceptions back.
  • Threads cannot be killed from outside. Stop them cooperatively: loop on an Event (while not stop.is_set():) and set it.
  • Return values: Thread ignores the target's return value. Use a queue.Queue, a shared structure with a lock, or ThreadPoolExecutor.
  • Prefer queue.Queue to share work. It is already thread-safe and removes most manual locking.
  • Deadlocks: if two threads take two locks in opposite orders they can wait forever. Always acquire locks in the same order, or use timeouts.
  • Choosing tools: threads for blocking I/O, asyncio for very many connections, processes for CPU-bound work.