Trace your Python code
with pyftrace.

pyftrace is an open source lightweight Python function tracing tool,
enables fast code analysis and debugging.

Installation #

Simply run:

$ pip install pyftrace

Basic Tracing #

Example code:

foo defined in line 1, called in line 8, returns 10
bar defined in line 5, called in line 2, returns 20

foobar.py


  1 def foo():
  2     bar()
  3     return 10
  4
  5 def bar():
  6     return 20
  7
  8 foo()

Get the calls and returns at a glance with a single line.

$ pyftrace foobar.py Running script: examples/foobar.py Called foo from line 9 Called bar from line 2 Returning bar-> 20 Called bar from line 3 Returning bar-> 20 Returning foo-> 10

Built-in & Path tracing #

pyftrace supports external library function/built-in trace.

builtins.py


  1 import os
  2
  3 def foo():
  4     print(os.path.basename(__file__))
  5
  6 foo()

You will get the following output with following format:

Called {function} @ {defined_path}:{line_number} from {called_path}:{line_number}
Returning {function} -> {return value} @ {returned_path}

$ pyftrace --verbose --path builtins.py Running script: builtins.py Called foo@/workspace/builtins.py:3 from /workspace/builtins.py:5 Called basename@/usr/lib/python3.8/posixpath.py:140 from /workspace/builtins.py:4 Called fspath from /usr/lib/python3.8/posixpath.py:142 Returning fspath Called _get_sep@/usr/lib/python3.8/posixpath.py:41 from /usr/lib/python3.8/posixpath.py:143 Called isinstance from /usr/lib/python3.8/posixpath.py:42 Returning isinstance Returning _get_sep-> / @ /usr/lib/python3.8/posixpath.py Called rfind from /usr/lib/python3.8/posixpath.py:144 Returning rfind Returning basename-> builtins.py @ /usr/lib/python3.8/posixpath.py Called print from /workspace/builtins.py:4 builtins.py Returning print Returning foo-> None @ /workspace/builtins.py

Execution Report #

You can also get the number of calls or duration per function.

fibonacci.py


  1 def fibonacci(n):
  2     if n <= 1:
  3         return n
  4     else:
  5         return fibonacci(n-1) + fibonacci(n-2)
  6
  7 result = fibonacci(5)

$ pyftrace --report fibonacci.py Running script: fibonacci.py Function Name | Total Execution Time | Call Count --------------------------------------------------------- fibonacci | 0.000332 seconds | 15

TUI mode #

pyftrace also provides a Terminal User Interface (TUI) mode.
Analyze large and complex codebases interactively.

PgUp or PgDn: Scroll up or down one page at a time.
Home or End: Jump to the beginning or end of the trace.
← or →: Scroll left or right horizontally.
q: Quit the TUI mode.

Tool Comparison #

There are other fantastic function tracing tools besides pyftrace (including Traceback inside Python).
But pyftrace has its own advantages:

	pyftrace	Traceback	py-spy	viztracer
Real-time Trace	O	X	O	O
TUI Mode	O	X	X	X
Built-in Trace	O	O	O	O
Execution Report (call count, duration)	O	X	X	O
Call-Return hierarchy	O	O	X	O

Help #

pyftrace was first introduced at Pycon Korea 2024 and is currently maintained by a single maintainer developer.

Your feedback is essential for the project's development.

If you have any feedback, please leave an issue, or at least support pyftrace with a star, it will be greatly appreciated.

Thanks for reading :)

Trace your Python code with pyftrace.