To install hunter run:

pip install hunter

The trace function

The hunter.trace function can take 2 types of arguments:

Note that hunter.trace will use hunter.Q when you pass multiple positional arguments or keyword arguments.

The Q function

The hunter.Q() function provides a convenience API for you:

  • Q(module='foobar') is converted to Query(module='foobar').
  • Q(module='foobar', action=Debugger) is converted to When(Query(module='foobar'), Debugger).
  • Q(module='foobar', actions=[CodePrinter, VarsPrinter('name')]) is converted to When(Query(module='foobar'), CodePrinter, VarsPrinter('name')).
  • Q(Q(module='foo'), Q(module='bar')) is converted to And(Q(module='foo'), Q(module='bar')).
  • Q(your_own_callback, module='foo') is converted to And(your_own_callback, Q(module='foo')).

Note that the default junction hunter.Q() uses is hunter.predicates.And.


All the builtin predicates (hunter.predicates.Query, hunter.predicates.When, hunter.predicates.And, hunter.predicates.Not and hunter.predicates.Or) support the |, & and ~ operators:

  • Query(module='foo') | Query(module='bar') is converted to Or(Query(module='foo'), Query(module='bar'))
  • Query(module='foo') & Query(module='bar') is converted to And(Query(module='foo'), Query(module='bar'))
  • ~Query(module='foo') is converted to Not(Query(module='foo'))


New in version 1.0.0: You can add startswith, endswith, in, contains, regex, lt, lte, gt, gte to your keyword arguments, just like in Django. Double underscores are not necessary, but in case you got twitchy fingers it’ll just work - filename__startswith is the same as filename_startswith.

New in version 2.0.0: You can also use these convenience aliases: sw (startswith), ew (endswith), rx (regex) and has (contains).


  • Query(module_in=['re', 'sre', 'sre_parse']) will match events from any of those modules.
  • ~Query(module_in=['re', 'sre', 'sre_parse']) will match events from any modules except those.
  • Query(module_startswith=['re', 'sre', 'sre_parse']) will match any events from modules that starts with either of those. That means repr will match!
  • Query(module_regex='(re|sre.*)$') will match any events from re or anything that starts with sre.


If you want to filter out stdlib stuff you’re better off with using Query(stdlib=False).


You can activate Hunter in three ways.

from code

import hunter

with an environment variable

Set the PYTHONHUNTER environment variable. Eg:

PYTHONHUNTER="module='os.path'" python

On Windows you’d do something like:

set PYTHONHUNTER=module='os.path'

The activation works with a clever .pth file that checks for that env var presence and before your app runs does something like this:

from hunter import *

That also means that it will do activation even if the env var is empty, eg: PYTHONHUNTER="".

with a CLI tool

If you got an already running process you can attach to it with hunter-trace. See Remote tracing for details.