Versions are year-based with a strict backward compatibility policy. The third digit is only for regressions.

19.2.0 (2019-10-16)

Backward-incompatible changes:

  • Python 3.4 is not supported anymore. It has been unsupported by the Python core team for a while now and its PyPI downloads are negligible.

    It’s very unlikely that structlog will break under 3.4 anytime soon, but we don’t test it anymore.




  • Full Python 3.8 support for structlog.stdlib.

  • Added more pass-through properties to structlog.stdlib.BoundLogger. To makes it easier to use it as a drop-in replacement for logging.Logger. #198

  • structlog.stdlib.ProcessorFormatter now takes a logger object as an optional keyword argument. This makes ProcessorFormatter work properly with stuctlog.stdlib.filter_by_level(). #219

  • now uses no colors by default, if colorama is not available. #215

  • now initializes colorama lazily, to prevent accidental side-effects just by importing structlog. #210

  • Added new processor that will set exc_info=True if the method’s name is exception and exc_info isn’t set at all. This is only necessary when the standard library integration is not used. It fixes the problem that in the default configuration, structlog.get_logger().exception("hi") in an except block would not print the exception without passing exc_info=True to it explicitly. #130, #173, #200, #204

  • A best effort has been made to make as much of structlog pickleable as possible to make it friendlier with multiprocessing and similar libraries. Some classes can only be pickled on Python 3 or using the dill library though and that is very unlikely to change.

    So far, the configuration proxy, structlog.processor.TimeStamper, structlog.BoundLogger, structlog.PrintLogger and have been made pickelable. Please report if you need any another class fixed. #126

  • Added a new thread-local API that allows binding values to a thread-local context explicitly without affecting the default behavior of bind(). #222, #225

  • Added pass_foreign_args argument to structlog.stdlib.ProcessorFormatter. It allows to pass a foreign log record’s args attribute to the event dictionary under the positional_args key. #228

  • now calls str() on the event value. #221

19.1.0 (2019-02-02)

Backward-incompatible changes:

  • As announced in 18.1.0, pip install -e .[dev] now installs all development dependencies. Sorry for the inconveniences this undoubtedly will cause!




  • structlog.ReturnLogger and structlog.PrintLogger now have a fatal() log method. #181

  • Under certain (rather unclear) circumstances, the frame extraction could throw an SystemError: error return without exception set. A workaround has been added. #174

  • structlog now tolerates passing through dicts to stdlib logging. #187, #188, #189

18.2.0 (2018-09-05)

Backward-incompatible changes:





  • Added structlog.stdlib.add_log_level_number() processor that adds the level number to the event dictionary. Can be used to simplify log filtering. #151

  • structlog.processors.JSONRenderer now allows for overwriting the default argument of its serializer. #77, #163

  • Added try_unbind() that works like unbind() but doesn’t raise a KeyError if one of the keys is missing. #171

18.1.0 (2018-01-27)

Backward-incompatible changes:



  • The meaning of the structlog[dev] installation target will change from “colorful output” to “dependencies to develop structlog” in 19.1.0.

    The main reason behind this decision is that it’s impossible to have a structlog in your normal dependencies and additionally a structlog[dev] for developement (pip will report an error).


  • Empty strings are valid events now. #110

  • Do not encapsulate Twisted failures twice with newer versions of Twisted. #144

  • now accepts a force_colors argument to output colored logs even if the destination is not a tty. Use this option if your logs are stored in files that are intended to be streamed to the console.

  • now accepts a level_styles argument for overriding the colors for individual levels, as well as to add new levels. See the docs for ConsoleRenderer.get_default_level_styles() for usage. #139

  • structlog.stdlib.BoundLogger.exception() now uses the exc_info argument if it has been passed instead of setting it unconditionally to True. #149

  • Default configuration now uses plain dicts on Python 3.6+ and PyPy since they are ordered by default.

  • Added structlog.is_configured() to check whether or not structlog has been configured.

  • Added structlog.get_config() to introspect current configuration.

17.2.0 (2017-05-15)

Backward-incompatible changes:





  • structlog.stdlib.ProcessorFormatter now accepts keep_exc_info and keep_stack_info arguments to control what to do with this information on log records. Most likely you want them both to be False therefore it’s the default. #109

  • structlog.stdlib.add_logger_name() now works in structlog.stdlib.ProcessorFormatter’s foreign_pre_chain. #112

  • Clear log record args in structlog.stdlib.ProcessorFormatter after rendering. This fix is for you if you tried to use it and got TypeError: not all arguments converted during string formatting exceptions. #116, #117

17.1.0 (2017-04-24)

The main features of this release are massive improvements in standard library’s logging integration. Have a look at the updated standard library chapter on how to use them! Special thanks go to Fabian Büchler, Gilbert Gilb’s, Iva Kaneva, insolite, and sky-code, that made them possible.

Backward-incompatible changes:

  • The default renderer now is if you don’t configure structlog. Colors are used if available and human-friendly timestamps are prepended. This is in line with our backward compatibility policy that explicitly excludes default settings.


  • Added structlog.stdlib.render_to_log_kwargs(). This allows you to use logging-based formatters to take care of rendering your entries. #98

  • Added structlog.stdlib.ProcessorFormatter which does the opposite: This allows you to run structlog processors on arbitrary logging.LogRecords. #79, #105

  • UNIX epoch timestamps from structlog.processors.TimeStamper are more precise now.

  • Added repr_native_str to structlog.processors.KeyValueRenderer and This allows for human-readable non-ASCII output on Python 2 (repr() on Python 2 behaves like ascii() on Python 3 in that regard). As per compatibility policy, it’s on (original behavior) in KeyValueRenderer and off (humand-friendly behavior) in ConsoleRenderer. #94

  • Added colors argument to and made it the default renderer. #78

  • Fixed bug with Python 3 and structlog.stdlib.BoundLogger.log(). Error log level was not reproductible and was logged as exception one time out of two. #92

  • Positional arguments are now removed even if they are empty. #82

16.1.0 (2016-05-24)

Backward-incompatible changes:

  • Python 3.3 and 2.6 aren’t supported anymore. They may work by chance but any effort to keep them working has ceased.

    The last Python 2.6 release was on October 29, 2013 and isn’t supported by the CPython core team anymore. Major Python packages like Django and Twisted dropped Python 2.6 a while ago already.

    Python 3.3 never had a significant user base and wasn’t part of any distribution’s LTS release.


  • Add a drop_missing argument to KeyValueRenderer. If key_order is used and a key is missing a value, it’s not rendered at all instead of being rendered as None. #67

  • Exceptions without a __traceback__ are now also rendered on Python 3.

  • Don’t cache loggers in lazy proxies returned from get_logger(). This lead to in-place mutation of them if used before configuration which in turn lead to the problem that configuration was applied only partially to them later. #72

16.0.0 (2016-01-28)


  • structlog.processors.ExceptionPrettyPrinter and structlog.processors.format_exc_info now support passing of Exceptions on Python 3.

  • Clean up the context when exiting structlog.threadlocal.tmp_bind in case of exceptions. #64

  • Be more more lenient about missing __name__s. #62

  • Add that renders the event dictionary aligned and with colors.

  • Use six for compatibility.

  • Add structlog.processors.UnicodeDecoder that will decode all byte string values in an event dictionary to Unicode.

  • Add serializer parameter to structlog.processors.JSONRenderer which allows for using different (possibly faster) JSON encoders than the standard library.

15.3.0 (2015-09-25)


  • Tolerate frames without a __name__, better. #58

  • Officially support Python 3.5.

  • Add structlog.ReturnLogger.failure and structlog.PrintLogger.failure as preparation for the new Twisted logging system.

15.2.0 (2015-06-10)


  • Allow empty lists of processors. This is a valid use case since #26 has been merged. Before, supplying an empty list resulted in the defaults being used.

  • Prevent Twisted’s log.err from quoting strings rendered by structlog.twisted.JSONRenderer.

  • Better support of logging.Logger.exception within structlog. #52

  • Add option to specify target key in structlog.processors.TimeStamper processor. #51

15.1.0 (2015-02-24)


  • Tolerate frames without a __name__.

15.0.0 (2015-01-23)


  • Add structlog.stdlib.add_log_level and structlog.stdlib.add_logger_name processors. #44

  • Add structlog.stdlib.BoundLogger.log. #42

  • Pass positional arguments to stdlib wrapped loggers that use string formatting. #19

  • structlog is now dually licensed under the Apache License, Version 2 and the MIT license. Therefore it is now legal to use structlog with GPLv2-licensed projects. #28

  • Add structlog.stdlib.BoundLogger.exception. #22

0.4.2 (2014-07-26)


  • Fixed a memory leak in greenlet code that emulates thread locals. It shouldn’t matter in practice unless you use multiple wrapped dicts within one program that is rather unlikely. #8

  • structlog.PrintLogger now is thread-safe.

  • Test Twisted-related code on Python 3 (with some caveats).

  • Drop support for Python 3.2. There is no justification to add complexity for a Python version that nobody uses. If you are one of the 0.350% that use Python 3.2, please stick to the 0.4 branch; critical bugs will still be fixed.

  • Officially support Python 3.4.

  • Allow final processor to return a dictionary. See the adapting chapter. #26

  • from structlog import * works now (but you still shouldn’t use it).

0.4.1 (2013-12-19)


  • Don’t cache proxied methods in structlog.threadlocal._ThreadLocalDictWrapper. This doesn’t affect regular users.

  • Various doc fixes.

0.4.0 (2013-11-10)

Backward-incompatible changes:


  • Add structlog.processors.StackInfoRenderer for adding stack information to log entries without involving exceptions. Also added it to default processor chain. #6

  • Allow optional positional arguments for structlog.get_logger that are passed to logger factories. The standard library factory uses this for explicit logger naming. #12

  • Add structlog.processors.ExceptionPrettyPrinter for development and testing when multiline log entries aren’t just acceptable but even helpful.

  • Allow the standard library name guesser to ignore certain frame names. This is useful together with frameworks.

  • Add meta data (e.g. function names, line numbers) extraction for wrapped stdlib loggers. #5

0.3.2 (2013-09-27)


  • Fix stdlib’s name guessing.

0.3.1 (2013-09-26)


  • Add forgotten structlog.processors.TimeStamper to API documentation.

0.3.0 (2013-09-23)


  • Greatly enhanced and polished the documentation and added a new theme based on Write The Docs, requests, and Flask.

  • Add Python Standard Library-specific BoundLogger that has an explicit API instead of intercepting unknown method calls. See structlog.stdlib.BoundLogger.

  • structlog.ReturnLogger now allows arbitrary positional and keyword arguments.

  • Add Twisted-specific BoundLogger that has an explicit API instead of intercepting unknown method calls. See structlog.twisted.BoundLogger.

  • Allow logger proxies that are returned by structlog.get_logger and structlog.wrap_logger to cache the BoundLogger they assemble according to configuration on first use. See the chapter on performance and the cache_logger_on_first_use argument of structlog.configure and structlog.wrap_logger.

  • Extract a common base class for loggers that does nothing except keeping the context state. This makes writing custom loggers much easier and more straight-forward. See structlog.BoundLoggerBase.

0.2.0 (2013-09-17)


  • Promote to stable, thus henceforth a strict backward compatibility policy is put into effect.

  • Add key_order option to structlog.processors.KeyValueRenderer for more predictable log entries with any dict class.

  • structlog.PrintLogger now uses proper I/O routines and is thus viable not only for examples but also for production.

  • Enhance Twisted support by offering JSONification of non-structlog log entries.

  • Allow for custom serialization in structlog.twisted.JSONRenderer without abusing __repr__.

0.1.0 (2013-09-16)

Initial release.