Guide · Open source

How to use PySnooper: trace Python functions without print statements

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

PySnooper is a small Python library that replaces hand-placed print statements. You add one decorator line to a function and it logs which lines ran, when they ran, and when local variables changed. This guide shows you how to install it, trace a whole function or a single block, and send the output to a file.

PySnoopercool-RR/PySnooper · ★ 16.6k · MIT Install options & downloads

Quick start

1Install the package. Run pip install pysnooper in your Python environment.
2Import the library. Add import pysnooper at the top of the file that contains the function.
3Add the decorator. Place @pysnooper.snoop() on the line above the function you want to trace.
4Run the function. Call the function as usual and read the log written to stderr.
5Redirect the output if needed. Pass a file path to the decorator, such as @pysnooper.snoop('/my/log/file.log'), to write the log to a file.
6Narrow the trace. Use a with pysnooper.snoop(): block to trace only part of a function.

Install PySnooper with pip

The best way to install PySnooper is with pip, the Python package manager. PySnooper only requires Python.

$ pip install pysnooper

Trace a whole function with a decorator

Import the library and add the @pysnooper.snoop() decorator above the function you want to inspect. The example in the README converts a number to a list of bits. Calling the function prints a log to stderr showing each line that ran and each new or changed local variable.

import pysnooper

@pysnooper.snoop()
def number_to_bits(number):
    if number:
        bits = []
        while number:
            number, remainder = divmod(number, 2)
            bits.insert(0, remainder)
        return bits
    else:
        return [0]

number_to_bits(6)

Trace only part of a function with a with block

If you do not want to trace an entire function, wrap the relevant lines in a with block. Only the code inside the block is logged. The README example shows this inside a function that picks the min, max and midpoint of a list.

import pysnooper
import random

def foo():
    lst = []
    for i in range(10):
        lst.append(random.randrange(1, 1000))

    with pysnooper.snoop():
        lower = min(lst)
        upper = max(lst)
        mid = (lower + upper) / 2
        print(lower, mid, upper)

foo()

Send the output to a log file

If stderr is hard to reach, pass a file path as the first argument to the decorator. The README also says you can pass a stream or a callable instead, and it will be used.

Pass a path to write the log to a file.
Pass a stream or a callable if you want to handle output yourself.

@pysnooper.snoop('/my/log/file.log')

Watch expressions and trace called functions

The watch option shows the values of expressions that are not plain local variables, such as attributes or dictionary lookups. The depth option also shows snoop lines for functions that your function calls. The README points to ADVANCED_USAGE.md for further options.

watch=('foo.bar', 'self.x["whatever"]') logs those expressions.
depth=2 extends tracing to functions called by your function.

@pysnooper.snoop(watch=('foo.bar', 'self.x["whatever"]'))
@pysnooper.snoop(depth=2)

What people use it for

Finding which branch of an if statement runs in a function you did not write.
Seeing when a local variable changes inside a loop, such as building a list of bits.
Tracing one block of a long function in a large codebase without setting up a debugger.
Logging attribute or dictionary values with the watch option while a function runs.

Frequently asked questions

How do I install PySnooper?

The README recommends installing it with pip using the command pip install pysnooper. It also lists conda (conda install -c conda-forge pysnooper), Arch Linux (yay -S python-pysnooper) and Fedora (dnf install python3-pysnooper) as other options.

Is PySnooper free to use?

PySnooper is released under the MIT license, according to the README's license section. The license text is copyright Ram Rachum and collaborators.

What are the requirements for PySnooper?

The source lists Python as the only prerequisite. It only works with Python code, so it cannot trace projects written in other languages.

Can PySnooper set breakpoints or step through code?

No. PySnooper only produces a log of lines run and variables changed. If you need breakpoints, stepping or interactive inspection, use a full debugger such as pdb or ipdb.

How does PySnooper compare to pdb, ipdb and icecream?

pdb and ipdb are interactive debuggers with breakpoints and stepping. icecream is a print-style helper. PySnooper sits between them: it needs only one decorator line and writes a structured trace without interaction.

Can I use PySnooper on performance-sensitive code?

The README does not describe PySnooper's overhead, and tracing adds output. Be cautious with it in performance-critical code and measure the impact yourself before relying on it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

PySnooper suits developers and beginners who want a quick, structured trace of a function without configuring a full debugger, especially in large existing codebases. If you need breakpoints, stepping or interactive inspection, or you are tuning performance-sensitive code, pick pdb, ipdb or a profiler instead.

Install options & downloads