#

Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed. By using non-blocking network I/O, Tornado can scale to tens of thousands of open connections, making it ideal for long polling, WebSockets, and other applications that require a long-lived connection to each user.

## Quick links

- Current version: 5.1.1 (download from PyPI, release notes)
- Source (github)
- Mailing lists: discussion and announcements
- Stack Overflow
- Wiki

## Hello, world

Here is a simple “Hello, world” example web app for Tornado:

    import tornado.ioloop
    import tornado.web

    class MainHandler(tornado.web.RequestHandler):
        def get(self):
            self.write("Hello, world")

    def make_app():
        return tornado.web.Application([
            (r"/", MainHandler),
        ])

    if __name__ == "__main__":
        app = make_app()
        app.listen(8888)
        tornado.ioloop.IOLoop.current().start()

This example does not use any of Tornado’s asynchronous features; for that see this simple chat room.

## Threads and WSGI

Tornado is different from most Python web frameworks. It is not based on WSGI, and it is typically run with only one thread per process. See the User’s guide for more on Tornado’s approach to asynchronous programming.

While some support of WSGI is available in the `tornado.wsgi` module, it is not a focus of development and most applications should be written to use Tornado’s own interfaces (such as `tornado.web`) directly instead of using WSGI.

In general, Tornado code is not thread-safe. The only method in Tornado that is safe to call from other threads is `IOLoop.add_callback`. You can also use `IOLoop.run_in_executor` to asynchronously run a blocking function on another thread, but note that the function passed to `run_in_executor` should avoid referencing any Tornado objects. `run_in_executor` is the recommended way to interact with blocking code.

## Installation

    pip install tornado

Tornado is listed in PyPI and can be installed with `pip`. Note that the source distribution includes demo applications that are not present when Tornado is installed in this way, so you may wish to download a copy of the source tarball or clone the git repository as well.

Prerequisites: Tornado 5.x runs on Python 2.7, and 3.4+ (Tornado 6.0 will require Python 3.5+; Python 2 will no longer be supported). The updates to the `ssl` module in Python 2.7.9 are required (in some distributions, these updates may be available in older python versions). In addition to the requirements which will be installed automatically by `pip` or `setup.py install`, the following optional packages may be useful:

- pycurl is used by the optional `tornado.curl_httpclient`. Libcurl version 7.22 or higher is required.
- Twisted may be used with the classes in `tornado.platform.twisted`.
- pycares is an alternative non-blocking DNS resolver that can be used when threads are not appropriate.
- monotonic or Monotime add support for a monotonic clock, which improves reliability in environments where clock adjustments are frequent. No longer needed in Python 3.

Platforms: Tornado should run on any Unix-like platform, although for the best performance and scalability only Linux (with `epoll`) and BSD (with `kqueue`) are recommended for production deployment (even though Mac OS X is derived from BSD and supports kqueue, its networking performance is generally poor so it is recommended only for development use). Tornado will also run on Windows, although this configuration is not officially supported and is recommended only for development use. Without reworking Tornado IOLoop interface, it’s not possible to add a native Tornado Windows IOLoop implementation or leverage Windows’ IOCP support from frameworks like AsyncIO or Twisted.

## Documentation

This documentation is also available in PDF and Epub formats.

- User’s guide
  - Introduction
  - Asynchronous and non-Blocking I/O
  - Coroutines
  - `Queue` example - a concurrent web spider
  - Structure of a Tornado web application
  - Templates and UI
  - Authentication and security
  - Running and deploying
- Web framework
  - `tornado.web` — `RequestHandler` and `Application` classes
  - `tornado.template` — Flexible output generation
  - `tornado.routing` — Basic routing implementation
  - `tornado.escape` — Escaping and string manipulation
  - `tornado.locale` — Internationalization support
  - `tornado.websocket` — Bidirectional communication to the browser
- HTTP servers and clients
  - `tornado.httpserver` — Non-blocking HTTP server
  - `tornado.httpclient` — Asynchronous HTTP client
  - `tornado.httputil` — Manipulate HTTP headers and URLs
  - `tornado.http1connection` – HTTP/1.x client/server implementation
- Asynchronous networking
  - `tornado.ioloop` — Main event loop
  - `tornado.iostream` — Convenient wrappers for non-blocking sockets
  - `tornado.netutil` — Miscellaneous network utilities
  - `tornado.tcpclient` — `IOStream` connection factory
  - `tornado.tcpserver` — Basic `IOStream`-based TCP server
- Coroutines and concurrency
  - `tornado.gen` — Generator-based coroutines
  - `tornado.locks` – Synchronization primitives
  - `tornado.queues` – Queues for coroutines
  - `tornado.process` — Utilities for multiple processes
- Integration with other services
  - `tornado.auth` — Third-party login with OpenID and OAuth
  - `tornado.wsgi` — Interoperability with other Python frameworks and servers
  - `tornado.platform.caresresolver` — Asynchronous DNS Resolver using C-Ares
  - `tornado.platform.twisted` — Bridges between Twisted and Tornado
  - `tornado.platform.asyncio` — Bridge between `asyncio` and Tornado
- Utilities
  - `tornado.autoreload` — Automatically detect code changes in development
  - `tornado.concurrent` — Work with `Future` objects
  - `tornado.log` — Logging support
  - `tornado.options` — Command-line parsing
  - `tornado.stack_context` — Exception handling across asynchronous callbacks
  - `tornado.testing` — Unit testing support for asynchronous code
  - `tornado.util` — General-purpose utilities
- Frequently Asked Questions
- Release notes
  - What’s new in Tornado 5.1.1
  - What’s new in Tornado 5.1
  - What’s new in Tornado 5.0.2
  - What’s new in Tornado 5.0.1
  - What’s new in Tornado 5.0
  - What’s new in Tornado 4.5.3
  - What’s new in Tornado 4.5.2
  - What’s new in Tornado 4.5.1
  - What’s new in Tornado 4.5
  - What’s new in Tornado 4.4.3
  - What’s new in Tornado 4.4.2
  - What’s new in Tornado 4.4.1
  - What’s new in Tornado 4.4
  - What’s new in Tornado 4.3
  - What’s new in Tornado 4.2.1
  - What’s new in Tornado 4.2
  - What’s new in Tornado 4.1
  - What’s new in Tornado 4.0.2
  - What’s new in Tornado 4.0.1
  - What’s new in Tornado 4.0
  - What’s new in Tornado 3.2.2
  - What’s new in Tornado 3.2.1
  - What’s new in Tornado 3.2
  - What’s new in Tornado 3.1.1
  - What’s new in Tornado 3.1
  - What’s new in Tornado 3.0.2
  - What’s new in Tornado 3.0.1
  - What’s new in Tornado 3.0
  - What’s new in Tornado 2.4.1
  - What’s new in Tornado 2.4
  - What’s new in Tornado 2.3
  - What’s new in Tornado 2.2.1
  - What’s new in Tornado 2.2
  - What’s new in Tornado 2.1.1
  - What’s new in Tornado 2.1
  - What’s new in Tornado 2.0
  - What’s new in Tornado 1.2.1
  - What’s new in Tornado 1.2
  - What’s new in Tornado 1.1.1
  - What’s new in Tornado 1.1
  - What’s new in Tornado 1.0.1
  - What’s new in Tornado 1.0

- Index
- Module Index
- Search Page

## Discussion and support

You can discuss Tornado on the Tornado developer mailing list, and report bugs on the GitHub issue tracker. Links to additional resources can be found on the Tornado wiki. New releases are announced on the announcements mailing list.

Tornado is available under the Apache License, Version 2.0.

This web site and all documentation is licensed under Creative Commons 3.0.