pysnooper

library1.2.3pypypi✓ verified 24d ago

PySnooper is a Python debugging tool often described as a 'poor man's debugger'. It allows developers to trace the execution of their code by automatically logging variable values, function calls, and execution lines to stdout or a file, without requiring traditional breakpoints or extensive manual print statements. The current stable version is 1.2.3. Recent GitHub activity indicates ongoing maintenance, including support for newer Python versions.

testing

pip install pysnooper

github ↗package ↗

INSTALL

IMPORT

SIG · PYSNOOPER

pysnooper

testingpythonv1.2.3

Install

1.6s avg

Import

42ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.042s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.042s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

snoop

✓ import pysnooper @pysnooper.snoop() def my_function(): pass

The primary way to use PySnooper is by applying the `@pysnooper.snoop()` decorator to a function you wish to inspect. This will log a detailed trace of execution, including variable changes and lines run. You can redirect output to a file and disable colored output for better readability in text editors. Alternatively, `pysnooper.snoop()` can be used as a context manager for specific code blocks.

import pysnooper import os # To demonstrate file output, create a dummy log file path log_file_path = os.path.join(os.getcwd(), 'pysnooper_output.log') @pysnooper.snoop(output=log_file_path, color=False) def number_to_bits(number): if number == 0: return [0] bits = [] while number: number, remainder = divmod(number, 2) bits.insert(0, remainder) return bits result = number_to_bits(6) print(f"Result for 6: {result}") # You can also use it as a context manager for a block of code def main_logic(): a = 10 b = 20 with pysnooper.snoop(output=log_file_path, color=False): temp = a + b final = temp * 2 print(f"Final value in main_logic: {final}") main_logic() # Cleanup (optional, for a runnable example) # import os # if os.path.exists(log_file_path): # os.remove(log_file_path)

pysnooper --version

Debug

Known issues

gotchaPySnooper can introduce noticeable performance overhead, especially in performance-critical sections or with extensive loops/execution. This is due to the detailed logging and introspection it performs.

fix

Use PySnooper judiciously on specific functions or code blocks where debugging is focused. Avoid using it on performance-sensitive hot paths unless absolutely necessary for debugging.

affects: All versions

gotchaFor complex functions, deep call stacks, or extensive loops, PySnooper's output can become extremely verbose and difficult to parse. This might make it harder to find the relevant debugging information amidst a large volume of logs.

fix

Utilize PySnooper's configuration options such as `depth` to limit tracing depth, `watch` to monitor specific expressions, or `thread_info`/`process_info` to filter output. Consider redirecting verbose output to a separate log file.

affects: All versions

gotchaWhen redirecting PySnooper's output to a file, the default colored output (ANSI escape codes) can make the log file unreadable in standard text editors. These escape codes are meant for terminal display.

fix

To get plain text output in a file, pass `color=False` to the `snoop` decorator or context manager, e.g., `@pysnooper.snoop(output='my_log.log', color=False)`.

affects: All versions

breakingPySnooper is designed for debugging and is not suitable for production environments. Leaving it enabled can expose internal state, negatively impact performance, and fill disk space with logs. It also adds a dependency that is only useful during development.

fix

Ensure PySnooper is disabled or removed from production builds. It can be globally disabled at runtime by setting the environment variable `PYSNOOPER_DISABLED=1`, which allows you to toggle it without modifying code.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pysnooper'

The pysnooper library is not installed in the Python environment where the code is being executed.

fix

pip install pysnooper

TypeError: Can't snoop to a non-file object: <function [function_name] at 0x...>

The `@pysnooper.snoop` decorator was used without parentheses, or the `output` parameter was provided with a value that is neither a string (file path) nor a file-like object.

fix

Add parentheses to call the decorator, e.g., `@pysnooper.snoop()`, or ensure the `output` parameter is a valid file path string or a file-like object like `sys.stdout`.

AttributeError: module 'pysnooper' has no attribute 'Snoop'

The `@pysnooper.snoop` decorator was called with a capitalized 'S' or another misspelling, attempting to access a non-existent attribute of the `pysnooper` module.

fix

Correct the capitalization to lowercase `snoop`: `@pysnooper.snoop()`

TypeError: 'function' object is not a context manager

The `pysnooper.snoop` function was used as a context manager without parentheses, meaning the function object itself was passed to the `with` statement, which expects a context manager.

fix

Add parentheses to call the `snoop` function when using it as a context manager: `with pysnooper.snoop():`

Upgrade

Version history

1.2.3latest on PyPI · released May 31, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/cool-RR/PySnooper ↗

packagehttps://pypi.org/project/pysnooper/ ↗