tornado.options — Command-line parsing

A command line parsing module that lets modules define their own options.

Each module defines its own options, e.g.:

from tornado.options import define, options

define("mysql_host", default="", help="Main user DB")
define("memcache_hosts", default="", multiple=True,
       help="Main user memcache servers")

def connect():
    db = database.Connection(options.mysql_host)

The main() method of your application does not need to be aware of all of the options used throughout your program; they are all automatically loaded when the modules are loaded. Your main() method can parse the command line or parse a config file with:

import tornado.options

Command line formats are what you would expect (“–myoption=myvalue”). Config files are just Python files. Global names become options, e.g.:

myoption = "myvalue"
myotheroption = "myothervalue"

We support datetimes, timedeltas, ints, and floats (just pass a ‘type’ kwarg to define). We also accept multi-value options. See the documentation for define() below.

tornado.options.define(name, default=None, type=None, help=None, metavar=None, multiple=False, group=None)[source]

Defines a new command line option.

If type is given (one of str, float, int, datetime, or timedelta) or can be inferred from the default, we parse the command line arguments based on the given type. If multiple is True, we accept comma-separated values, and the option value is always a list.

For multi-value integers, we also accept the syntax x:y, which turns into range(x, y) - very useful for long integer ranges.

help and metavar are used to construct the automatically generated command line help string. The help message is formatted like:

--name=METAVAR      help string

group is used to group the defined options in logical groups. By default, command line options are grouped by the defined file.

Command line option names must be unique globally. They can be parsed from the command line with parse_command_line() or parsed from a config file with parse_config_file.


Global options dictionary. Supports both attribute-style and dict-style access.


Parses all options given on the command line (defaults to sys.argv).

Note that args[0] is ignored since it is the program name in sys.argv.

We return a list of all arguments that are not parsed as options.


Parses and loads the Python config file at the given path.


Prints all the command line options to stdout.


Turns on formatted logging output as configured.

This is called automatically by parse_command_line.

exception tornado.options.Error[source]

Exception raised by errors in the options module.

Previous topic

tornado.httputil — Manipulate HTTP headers and URLs

Next topic

tornado.process — Utilities for multiple processes

This Page