How to Migrate To Python 3

Once you have Python 3 installed and working, it’s time to upgrade your code. In most cases, it’s not hard to upgrade your code, and you can follow multiple strategies.

What you need to do is:

  • Upgrade your own code
  • Upgrade to newer versions of your dependencies

Luckily, there are some tools that can help us!

2to3

2to3 is a Python program that reads Python 2 source code and applies a series of fixers to transform it into valid Python 3 code. The standard library contains a rich set of fixers that will handle almost all code.

A notable change in Python 3 is that print is now a function called print(). For example, this Python 2 code:

def greet(name):
    print "Hello, {0}!".format(name)
print "What's your name?"
name = raw_input()
greet(name)

Can be converted by calling:

$ 2to3 greet.py

By default, this only prints the difference to your screen for inspection. If it looks alright, you can use the -w option to actually changes the file:

$ 2to3 -w greet.py

The original file is changed and the old file will be saved as greet.py.bak. The result:

def greet(name):
     print("Hello, {0}!".format(name))
 print("What's your name?")
 name = input()
 greet(name)

Some of the more interesting flags for 2to3 are:

FlagFunction
-llist all fixers
-xexcludes selected fixer
-fexplicitly run only this fix
-wUpdate the file instead of printing to stdout

Please go ahead and read the full 2to3 documentation before you start converting your code.

Six

six is a Python 2 and 3 compatibility library. The project helps codebases to support both Python 2 and 3. I would recommend migrating completely to Python 3 with 2to3, but if you can’t, for whatever reason, you can at least make your codebase work on both versions.

Six offers functions that smooth the differences in syntax between Python 2 and 3. An easy-to-grasp example of this is six.print_(). In Python 3, printing is done with the print() function. In Python 2, print works without the parentheses. By using six.print_(), you can support both languages with one statement.

A few nice to knows:

  • The name six comes from the fact that two times three equals six.
  • For a similar library, also check out the future package.

Upgrade your packages

You probably need to upgrade the packages you depend on. For each package version you are using, try to find out if it already supports Python 3. If it doesn’t, find a version that does. You may have to alter some code since APIs tend to change over time.

If you’re in a hurry, and your package’s API has changed significantly, you can try finding the lowest version of the package that supports Python 3. The chances are that the API hasn’t changed as much in the lower version. It’s almost always better to use the latest versions, but at least it’s a step in the right direction!

Check for a minimum-required Python version

Once migrated, add a check for the Python version in your code. This way, you can ensure you and your users are not running your script with an incompatible version, which will cause incomprehensible errors and frustration. Use a simple check like this:

if not sys.version_info > (2, 7):
   # berate your user for running a 10 year
   # python version
elif not sys.version_info >= (3, 5):
   # Kindly tell your user (s)he needs to upgrade
   # because you're using 3.5 features

Please help us and share this article

About the author

Erik is the owner of Python Land and the author of many of the articles and tutorials on this website. He's been working as a professional software developer for 25 years, and he holds a Master of Science degree in computer science. His favorite language of choice: Python!