Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

This is experimental module that enables American Fuzzy Lop fork server and instrumentation for pure-Python code.


  • Add this code (ideally, after all other modules are already imported) to the target program:

    import afl
  • The instrumentation is currently implemented with a trace function, which is called whenever a new local scope is entered. You might need to wrap the code of the main program in a function to get it instrumented correctly.

  • Optionally, add this code at the end of the target program:


    This should speed up fuzzing considerably, at the risk of not catching bugs that could happen during normal exit.

  • For persistent mode, wrap the tested code in this loop:

    while afl.loop(N):

    where N is the number of inputs to process before restarting.

    You shouldn't call afl.init() in this case.

    If you read input from sys.stdin, you must rewind it in every loop iteration:

    afl-fuzz ≥ 1.82b is required for this feature.

  • Use py-afl-fuzz instead of afl-fuzz:

    $ py-afl-fuzz [options] -- /path/to/fuzzed/python/script [...]
  • The instrumentation is a bit slow at the moment, so you might want to enable the dumb mode (-n), while still leveraging the fork server.

    afl-fuzz ≥ 1.95b is required for this feature.

Environment variables

The following environment variables affect python-afl behavior:


If this variable is set, python-afl installs an exception hook that kills the current process with the selected signal. That way afl-fuzz can treat unhandled exceptions as crashes.

By default, py-afl-fuzz, py-afl-showmap, python-afl-cmin, and py-afl-tmin set this variable to SIGUSR1.

You can set PYTHON_AFL_SIGNAL to another signal; or set it to 0 to disable the exception hook.


Persistent mode is enabled only if this variable is set.

py-afl-fuzz sets this variable automatically, so there should normally no need to set it manually.

TSTL test harness code is ignored if this variable is set; relevant only to users of TSTL interface to python-afl.


Multi-threaded code is not supported.

Further reading


To build the module, you will need:

  • Python 2.6+ or 3.2+
  • Cython ≥ 0.19 (only at build time)

py-afl-fuzz requires AFL proper to be installed.