What’s new in Tornado 5.1

July 12, 2018

Deprecation notice

  • Tornado 6.0 will drop support for Python 2.7 and 3.4. The minimum supported Python version will be 3.5.2.
  • The tornado.stack_context module is deprecated and will be removed in Tornado 6.0. The reason for this is that it is not feasible to provide this module’s semantics in the presence of async def native coroutines. ExceptionStackContext is mainly obsolete thanks to coroutines. StackContext lacks a direct replacement although the new contextvars package (in the Python standard library beginning in Python 3.7) may be an alternative.
  • Callback-oriented code often relies on ExceptionStackContext to handle errors and prevent leaked connections. In order to avoid the risk of silently introducing subtle leaks (and to consolidate all of Tornado’s interfaces behind the coroutine pattern), callback arguments throughout the package are deprecated and will be removed in version 6.0. All functions that had a callback argument removed now return a Future which should be used instead.
  • Where possible, deprecation warnings are emitted when any of these deprecated interfaces is used. However, Python does not display deprecation warnings by default. To prepare your application for Tornado 6.0, run Python with the -Wd argument or set the environment variable PYTHONWARNINGS to d. If your application runs on Python 3 without deprecation warnings, it should be able to move to Tornado 6.0 without disruption.


  • OAuthMixin._oauth_get_user_future may now be a native coroutine.
  • All callback arguments in this package are deprecated and will be removed in 6.0. Use the coroutine interfaces instead.
  • The OAuthMixin._oauth_get_user method is deprecated and will be removed in 6.0. Override _oauth_get_user_future instead.


  • The command-line autoreload wrapper is now preserved if an internal autoreload fires.
  • The command-line wrapper no longer starts duplicated processes on windows when combined with internal autoreload.




  • The behavior of raise_error=False is changing in 6.0. Currently it suppresses all errors; in 6.0 it will only suppress the errors raised due to completed responses with non-200 status codes.
  • The callback argument to AsyncHTTPClient.fetch is deprecated and will be removed in 6.0.
  • tornado.httpclient.HTTPError has been renamed to HTTPClientError to avoid ambiguity in code that also has to deal with tornado.web.HTTPError. The old name remains as an alias.
  • tornado.curl_httpclient now supports non-ASCII characters in username and password arguments.
  • .HTTPResponse.request_time now behaves consistently across simple_httpclient and curl_httpclient, excluding time spent in the max_clients queue in both cases (previously this time was included in simple_httpclient but excluded in curl_httpclient). In both cases the time is now computed using a monotonic clock where available.
  • HTTPResponse now has a start_time attribute recording a wall-clock (time.time) timestamp at which the request started (after leaving the max_clients queue if applicable).


  • parse_multipart_form_data now recognizes non-ASCII filenames in RFC 2231/5987 (filename*=) format.
  • HTTPServerRequest.write is deprecated and will be removed in 6.0. Use the methods of request.connection instead.
  • Malformed HTTP headers are now logged less noisily.




  • Improved compatibility with GNU Hurd.



  • TornadoReactor and TwistedIOLoop are deprecated and will be removed in 6.0. Instead, Tornado will always use the asyncio event loop and twisted can be configured to do so as well.




  • New method RequestHandler.detach can be used from methods that are not decorated with @asynchronous (the decorator was required to use self.request.connection.detach().
  • RequestHandler.finish and RequestHandler.render now return Futures that can be used to wait for the last part of the response to be sent to the client.
  • FallbackHandler now calls on_finish for the benefit of subclasses that may have overridden it.
  • The asynchronous decorator is deprecated and will be removed in 6.0.
  • The callback argument to RequestHandler.flush is deprecated and will be removed in 6.0.