We tend to view our Python programs as linear scripts that we feed into an interpreter, which then dutifully executes them. But the CPython interpreter isn’t a simple, stateless-processor of text files; it is a complex, stateful virtual machine running in memory. It manages memory, schedules threads, and juggles execution contexts. Most of the time, we’re happy to live on top of this abstraction layer. Sometimes, however, we need to peel back the curtain and see the gears of the machine itself. The standard entry point for this kind of introspection is the sys module.
Most developers are familiar with the common parts of sys: you might use sys.argv to get command-line arguments or manipulate sys.path to control module imports. These are the safe, documented, public-facing interfaces. But lurking just beneath the surface are functions and attributes prefixed with an underscore, a long-standing Python convention for “internal use only.” These are the levers connected directly to the interpreter’s core machinery, and one of the most powerful is sys._current_frames().
As the name suggests, this function gives you a snapshot of what every single active thread in the process is doing at the exact moment you call it. It doesn’t pause them; it just instantaneously grabs a reference to the top-most stack frame of each one. The function returns a dictionary where the keys are thread identifiers (integers) and the values are the corresponding frame objects. That’s, in essence, a real-time process-wide debugger hook handed to you on a silver platter.
Let’s see it in action. Ponder a simple program with a few worker threads spinning in a loop:
import sys
import threading
import time
def worker(name, duration):
"""A simple worker function that simulates doing work."""
print(f"Worker '{name}' starting.")
while True:
# Simulate some I/O-bound work
time.sleep(duration)
print(f"Worker '{name}' is working...")
# Create and start a few threads
threads = []
for i in range(3):
t = threading.Thread(target=worker, args=(f"W-{i}", i + 1), daemon=True)
threads.append(t)
t.start()
# Let the threads run for a bit
time.sleep(2.5)
# Now, let's peek into what they're doing
print("n--- Capturing current frames ---")
current_frames = sys._current_frames()
main_thread_id = threading.get_ident()
for thread_id, frame in current_frames.items():
thread_name = "MainThread"
for t in threads:
if t.ident == thread_id:
thread_name = t.name
break
print(f"nThread ID: {thread_id} (Name: {thread_name})")
print(f" Current function: {frame.f_code.co_name}")
print(f" Current line no: {frame.f_lineno}")
print(f" Locals: {frame.f_locals}")
When you run this, the output will vary slightly depending on timing, but it will look something like this:
Worker 'W-0' starting.
Worker 'W-1' starting.
Worker 'W-2' starting.
Worker 'W-0' is working...
Worker 'W-1' is working...
--- Capturing current frames ---
Thread ID: 140237592495936 (Name: MainThread)
Current function: <module>
Current line no: 26
Locals: {'__name__': '__main__', ... 'main_thread_id': 140237592495936}
Thread ID: 140237510252096 (Name: W-0)
Current function: worker
Current line no: 8
Locals: {'name': 'W-0', 'duration': 1}
Thread ID: 140237501859392 (Name: W-1)
Current function: worker
Current line no: 8
Locals: {'name': 'W-1', 'duration': 2}
Thread ID: 140237493466688 (Name: W-2)
Current function: worker
Current line no: 8
Locals: {'name': 'W-2', 'duration': 3}
Look at what we’ve just captured. For each thread, identified by its unique integer ID, we have a frame object. This object is a goldmine. It is a direct window into the execution context of that thread. In the example, we’ve pulled out the name of the function currently being executed (frame.f_code.co_name), the exact line number it is on (frame.f_lineno), and even a dictionary of its local variables (frame.f_locals). Notice how for each worker, the duration local variable matches what we passed in. We can see that all three workers are currently paused inside the time.sleep() call on line 8. That’s not an approximation or a log message; it’s the ground truth of the interpreter’s state. The frame object is the fundamental data structure that represents a call on Python’s call stack, containing everything needed to resume execution from that point. And with sys._current_frames(), we have a reference to the very top of every single one of those stacks.
Black Magic for Real-Time Thread Inspection
But we’re just scratching the surface. The frame object we retrieved is only the top of the stack—the function that’s currently executing. What about the function that called it? And the one that called that one? The true power of this technique is revealed when you realize that each frame object holds a reference to its caller. This reference is stored in the f_back attribute. Each frame object is, in effect, a node in a singly-linked list that represents the entire call stack for that thread. By starting at the top frame and repeatedly following the f_back reference, we can walk all the way down to the very first function call that started the thread.
Let’s modify our previous example to do exactly this. We’ll write a small helper function to traverse the stack and print it in a familiar format, similar to a standard Python traceback.
import sys
import threading
import time
def worker(name, duration):
"""A simple worker function that simulates doing work."""
print(f"Worker '{name}' starting.")
while True:
time.sleep(duration)
print(f"Worker '{name}' is working...")
def print_stack(frame):
"""Walks and prints a stack trace from a given frame."""
stack = []
while frame:
filename = frame.f_code.co_filename
lineno = frame.f_lineno
func_name = frame.f_code.co_name
stack.append(f' File "{filename}", line {lineno}, in {func_name}')
frame = frame.f_back
# Print in the standard traceback order (oldest call last)
for line in reversed(stack):
print(line)
# Create and start a few threads
threads = []
for i in range(3):
# daemon=True so they exit when the main thread exits
t = threading.Thread(target=worker, args=(f"W-{i}", i + 5), daemon=True, name=f"W-{i}")
threads.append(t)
t.start()
# Let the threads run for a bit before we inspect them
time.sleep(1.5)
# Build a map from thread ID to thread name for easier lookup
thread_map = {t.ident: t.name for t in threading.enumerate()}
print("n--- Capturing current frames with full stack traces ---")
current_frames = sys._current_frames()
for thread_id, frame in current_frames.items():
thread_name = thread_map.get(thread_id, f"Unknown_Thread_{thread_id}")
print(f"n--- Stack for thread {thread_id} ({thread_name}) ---")
print_stack(frame)
The output is now far more revealing. Instead of just seeing that the workers are in time.sleep, we see the entire sequence of calls that got them there. For a worker thread, the stack trace will look something like this (file paths and line numbers may vary):
--- Stack for thread 140165088261696 (W-0) --- File "/usr/lib/python3.9/threading.py", line 917, in _bootstrap File "/usr/lib/python3.9/threading.py", line 980, in _bootstrap_inner File "test.py", line 8, in worker File "test.py", line 7, in <module>
That is effectively the same information a debugger would give you, but we’ve obtained it programmatically, at runtime, without attaching any external tools or even pausing the program in a meaningful way. The call to _current_frames() is extremely fast as it doesn’t do a lot of work itself, mostly just grabbing existing pointers. We see the call to our worker function. We see that worker called time.sleep. We can even see the internal machinery of the threading module itself, with the _bootstrap_inner and _bootstrap methods that are responsible for kicking off the thread’s target function. That is an incredibly powerful primitive. You could build a live monitoring dashboard that shows what every thread is doing, updated in real time. You could write a watchdog that periodically samples all thread stacks and raises an alert if a thread appears to be stuck in the same function for too long, a simple but effective way to detect deadlocks or infinite loops. The frame object also contains f_globals (the module’s global namespace) and f_code, a code object that contains a wealth of information about the function itself, including its argument names, local variable names, and even the raw bytecode. By combining these, you can construct a detailed, high-fidelity portrait of your application’s state at any given moment.
This isn’t just introspection; it is a form of live, in-process archaeology, digging through the layers of the execution state to understand precisely what the machine is doing. The possibilities for advanced debugging, profiling, and monitoring tools that you can build with this one function are vast. For instance, imagine you are chasing a race condition that only occurs on a production system under heavy load. Attaching a conventional debugger is often not an option, as it would halt the entire process and likely violate service-level agreements. Instead, you could add a signal handler or a simple web endpoint that, when triggered, calls sys._current_frames(), formats all the stack traces, and writes them to a log file. This gives you a complete snapshot of the process state at the exact moment of interest without significant interruption. This is the kind of surgical precision that turns impossible-to-diagnose production bugs into solvable engineering problems. The key is understanding that the Python interpreter isn’t a black box; it is a living system whose internal state is, to some extent, accessible and queryable, if you know where to look and aren’t afraid of a little black magic. The data is all there, waiting in memory, structured in these frame objects.
