Install & Compatibility
Where this runs
tested against v0.6.0 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.523s · 27MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.3s · import 0.504s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
snoop
✓ from snoop import snoop
pp
✓ from snoop import pp
✗ import snoop.pp
The pp object is typically imported directly from the snoop package.
spy
✓ from snoop import spy
✗ from snoop.spy import spy
The spy decorator is imported directly from the top-level snoop package, not a submodule. Requires 'birdseye' package to be installed.
install
✓ from snoop import install
✗ snoop.configure()
Global configuration for snoop is done via the 'install' function, not a 'configure' method on the main snoop object.
Demonstrates the basic usage of the `@snoop` decorator to automatically trace the execution and display variable values within a function. The output is sent to `stderr` by default.
from snoop import snoop
@snoop
def calculate_total(prices, tax_rate):
total = sum(prices)
tax = total * tax_rate
final_total = total + tax
return final_total
prices_list = [10, 20, 30]
rate = 0.08
result = calculate_total(prices_list, rate)
print(f"Final Total: {result}")
Debug
Known issues
breakingSnoop's API differs from PySnooper. Specifically, arguments like 'output', 'thread_info', 'prefix', and 'overwrite' are passed to `snoop.install()` or handled as `snoop` decorator arguments with different names (e.g., 'out' instead of 'output', 'columns' for thread info).fixConsult the snoop documentation for correct argument names and usage. For global configuration, use `snoop.install(out=..., prefix=..., columns=...)`.
affects: All versions since 0.1.0 (initial release) compared to PySnooper
gotchaThe `@spy` decorator (which integrates with `birdseye`) incurs a significant performance overhead and should be used cautiously, especially in functions with many loop iterations or performance-critical sections.fixUse `@snoop` for general debugging. Only use `@spy` when the enhanced visual debugging of `birdseye` is strictly necessary and performance is not a primary concern. Ensure 'birdseye' is installed separately via `pip install birdseye`.
affects: All versions
gotchaBy default, `snoop` outputs its trace to `sys.stderr`. If you are running scripts where `stderr` is not visible or captured, you might not see any output.fixRedirect output using `snoop.install(out=sys.stdout)` to print to standard output, or `snoop.install(out='path/to/log.txt', overwrite=True)` to write to a file.
affects: All versions
gotchaSnoop is explicitly designed for Python >=3.8. Attempting to use it with older Python versions (e.g., Python 2.7) will result in syntax errors or `ModuleNotFoundError`.fixEnsure your project is running on Python 3.8 or newer.
affects: <=3.7
Errors
Common errors & fixes
NameError: name 'snoop' is not defined
The `snoop` decorator or function was used without being imported first.
fixAdd `from snoop import snoop` at the top of your file. Alternatively, for global availability, use `from snoop import install` and call `install()` (e.g., `install(builtins=True)` to make `snoop` directly available).
ModuleNotFoundError: No module named 'birdseye'
The `@spy` decorator was used, but the `birdseye` library, which it depends on, is not installed.
fixInstall the `birdseye` dependency: `pip install birdseye`.
TypeError: snoop() got an unexpected keyword argument 'output'
You are attempting to use PySnooper's `output` argument with `snoop`, which uses a different parameter name (`out`) and context for global configuration.
fixFor global output configuration, use `from snoop import install` and then `install(out='your_file.log')`. The `@snoop` decorator itself does not take an `out` argument directly.
No snoop output appears in the console.
Snoop's output defaults to `sys.stderr`. In some environments or execution contexts (e.g., IDEs, certain CI/CD pipelines), `stderr` might not be directly displayed or captured where you expect.
fixExplicitly direct snoop's output to `sys.stdout` or a file using `from snoop import install` and then `install(out=sys.stdout)` or `install(out='debug.log', overwrite=True)`.
Upgrade
Version history
0.6.0latest on PyPI · released Oct 6, 2024
Audit
Dependencies
birdseyeoptionalRequired for the @spy decorator, which combines snoop with the birdseye debugger for enhanced visual debugging.