Quick-start guide¶

You can use future to help to port your code from Python 2 to Python 3 today – and still have it run on Python 2.

If you already have Python 3 code, you can instead use future to offer Python 2 compatibility with almost no extra work.

Installation¶

To install the latest stable version, type:

pip install future

If you would prefer the latest development version, it is available here.

On Python 2.6, three packages containing backports of standard library modules in Python 2.7+ are needed for small parts of the code:

pip install importlib       # for future.standard_library.import_ function only
pip install unittest2       # to run the test suite
pip install argparse        # for the backported http.server module from Py3.3

Unless these features are used on Python 2.6 (only), future has no dependencies.

If you are writing code from scratch¶

The easiest way is to start each new module with these lines:

from __future__ import (absolute_import, division,
                        print_function, unicode_literals)
from builtins import *

Then write standard Python 3 code. The future package will provide support for running your code on Python 2.6 and 2.7 mostly unchanged.

For explicit import forms, see Explicit imports.
For more details, see What else you need to know.
For a cheat sheet, see Cheat Sheet: Writing Python 2-3 compatible code.

To convert existing Python 3 code¶

To offer backward compatibility with Python 2 from your Python 3 code, you can use the pasteurize script. This adds these lines at the top of each module:

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from __future__ import unicode_literals

from builtins import open
from builtins import str
# etc., as needed

from future import standard_library
standard_library.install_aliases()

and converts several Python 3-only constructs (like keyword-only arguments) to a form compatible with both Py3 and Py2. Most remaining Python 3 code should simply work on Python 2.

See pasteurize: Py3 to Py2/3 for more details.

To convert existing Python 2 code¶

The futurize script passes Python 2 code through all the appropriate fixers to turn it into valid Python 3 code, and then adds __future__ and future package imports to re-enable compatibility with Python 2.

For example, running futurize turns this Python 2 code:

import ConfigParser                 # Py2 module name

class Upper(object):
    def __init__(self, iterable):
        self._iter = iter(iterable)
    def next(self):                 # Py2-style iterator interface
        return next(self._iter).upper()
    def __iter__(self):
        return self

itr = Upper('hello')
print next(itr),
for letter in itr:
    print letter,                   # Py2-style print statement

into this code which runs on both Py2 and Py3:

from __future__ import print_function
from future import standard_library
standard_library.install_aliases()
from future.builtins import next
from future.builtins import object
import configparser                 # Py3-style import

class Upper(object):
    def __init__(self, iterable):
        self._iter = iter(iterable)
    def __next__(self):             # Py3-style iterator interface
        return next(self._iter).upper()
    def __iter__(self):
        return self

itr = Upper('hello')
print(next(itr), end=' ')           # Py3-style print function
for letter in itr:
    print(letter, end=' ')

To write out all the changes to your Python files that futurize suggests, use the -w flag.

For complex projects, it is probably best to divide the porting into two stages. Stage 1 is for “safe” changes that modernize the code but do not break Python 2.6 compatibility or introduce a depdendency on the future package. Stage 2 is to complete the process.

See Stage 1: “safe” fixes and Stage 2: Py3-style code with wrappers for Py2 for more details.

Standard library reorganization¶

future supports the standard library reorganization (PEP 3108) via one of several mechanisms, allowing most moved standard library modules to be accessed under their Python 3 names and locations in Python 2:

from future import standard_library
standard_library.aliases()

# Then these Py3-style imports work on both Python 2 and Python 3:
import socketserver
import queue
import configparser
from collections import UserDict, UserList, UserString
from collections import Counter, OrderedDict   # even on Py2.6
from itertools import filterfalse, zip_longest

import html
import html.entities
import html.parser

import http
import http.client
import http.server
import http.cookies
import http.cookiejar

import urllib.request
import urllib.parse
import urllib.response
import urllib.error
import urllib.robotparser

import xmlrpc.client
import xmlrpc.server

and others. For a complete list, see List of renamed standard library modules.

Python 2-only dependencies¶

If you have dependencies that support only Python 2, you may be able to use the past module to automatically translate these Python 2 modules to Python 3 upon import. First, install the Python 2-only package into your Python 3 environment:

$ pip3 install mypackagename --no-compile   # to ignore SyntaxErrors

(or use pip if this points to your Py3 environment.)

Then add the following code at the top of your (Py3 or Py2/3-compatible) code:

from past import autotranslate
autotranslate(['mypackagename'])
import mypackagename

This feature is experimental, and we would appreciate your feedback on how well this works or doesn’t work for you. Please file an issue here or post to the python-porting mailing list.

For more information on the automatic translation feature, see Using Python 2-only dependencies on Python 3.

Next steps¶

For more information about writing Py2/3-compatible code, see: