Python Futurize: Convert Python 2 to 3 Safely | ShillehTek

Video Tutorial (Optional)

Watch first if you want to follow the futurize workflow in real time.

Project Overview

Convert Python2 to 3 With Backwards Compatibility Using Future: In this tutorial, you use the Python futurize tool (from the future package) to convert Python 2 code to run on Python 3 while keeping backward compatibility for legacy projects.

Python 3 has been out for nearly 15 years and is the current standard (for example, 3.10). Download Python here: https://www.python.org/downloads/.

Some legacy projects remain on Python 2 due to large dependency trees, where an unsafe upgrade can break other dependencies and disrupt production pipelines. The futurize workflow helps reduce risk by applying changes in stages.

• Time: 10 to 20 minutes
• Skill level: Beginner
• What you will build: A repeatable process to convert a Python 2 script toward Python 3 compatibility using futurize stage 1 and stage 2

Parts List

From ShillehTek

• None

External

• Python (download): https://www.python.org/downloads/
• future package (includes futurize CLI)

Note: Stage 1 is designed to create a safer diff and is not always enough to make the script runnable in Python 3. If stage 1 already runs on both Python 2 and Python 3 for your case, you can skip stage 2.

Step-by-Step Guide

Step 1 - Install the future package

Goal: Install the tooling needed to run futurize.

What to do: Install the package using pip.

Code:

pip install future

Expected result: The future package is installed and the futurize command is available.

Step 2 - Convert the script with stage 1 futurization

Goal: Apply the first, lower risk set of changes and generate an initial porting diff.

What to do: Run stage 1 on your target file. The -w flag writes changes back to the file.

Code:

futurize --stage1 -w <path_to_file>

Expected result: The file is modified to include safer, preliminary changes, but it may still not run in Python 3 (which is common after stage 1).

Step 3 - Run stage 2 futurization

Goal: Apply the next set of changes to make the script runnable in Python 3, while still supporting Python 2 through the future dependency.

What to do: Run stage 2 on the same file. If stage 1 already works in both Python 2 and 3 for your script, you can skip this step.

Code:

futurize --stage2 -w <path_to_file>

Expected result: The code includes the future dependency changes and is runnable in Python 3. Example output:

Hello world
1
2
name 'trying_to_check_error' is not defined Error Caused

Step 4 - Post futurization testing

Goal: Confirm your converted code behaves the same in Python 2 and Python 3.

What to do: Run your tests (or manually execute the script) in both Python 2 and Python 3 and compare results. If your application handles a lot of string and binary data, expect possible encoding issues.

Tools like futurize cannot automatically fix semantic logic differences, so any semantic incompatibilities may require manual refactoring.

Expected result: Your application produces consistent results on both Python 2 and Python 3, or you have a clear list of manual refactors needed to resolve remaining issues.

Conclusion

You used the Python futurize tool from the future package to move Python 2 code toward Python 3 compatibility using a staged approach. This workflow is useful for legacy systems where full Python 2 removal is risky due to dependency constraints.

If it is possible to decouple from Python 2 completely, you should do so, since Python 3 is fully supported and provides many benefits over Python 2, including performance improvements.

Want parts and tools for your next build? Grab what you need from ShillehTek.com. If you want help planning a migration path or building a reliable automation pipeline, check out our IoT consulting services.