2to3

Display the changes that would be performed without performing them (dry-run)

$ 2to3 [path/to/file.py]

$ 2to3 --write [path/to/file.py]

$ 2to3 --write [path/to/file.py] --fix [raw_input] --fix [print]

$ 2to3 --write [path/to/file.py] --nofix [has_key] --nofix [isinstance]

$ 2to3 --list-fixes

$ 2to3 --output-dir [path/to/python3_directory] --write-unchanged-files --nobackups [path/to/python2_directory]

$ 2to3 --processes [4] --output-dir [path/to/python3_directory] --write --nobackups --no-diff [path/to/python2_directory]

2to3 [options] file_or_directory ...
2to3 -f <fixer> | --fix <fixer> ... [-x <fixer> | --nofix <fixer> ...] [-w | --write] [-n | --no-backup] [-o <dir> | --output-dir <dir>] [--diffs | --no-diffs] [--add-fixer <fixer>] [--list-fixers] [-v | --verbose] path ...

-w, --write
    Write the modified files back to their original locations. Creates a `*.bak` backup unless `-n` is used.

-n, --no-backup
    Don't create `*.bak` backup files when writing changes with `-w`.

-o

2to3 is a Python program that reads Python 2.x source code and applies a series of 'fixers' to transform it into valid Python 3.x code. It's a standard utility included with Python distributions, designed to assist developers in migrating their projects from the older Python 2 syntax and features to the newer Python 3. This tool automates many of the common code changes, such as print statements to print functions, `xrange` to `range`, integer division, and various module renames.

While `2to3` handles a significant portion of the conversion, it is not always perfect, especially with more complex codebases or those relying heavily on specific Python 2 library behaviors that have no direct Python 3 equivalent. It typically works by analyzing the code, proposing changes, and either displaying a diff or writing the modified code to new files (optionally creating backups). It serves as a valuable first step in the migration process, significantly reducing manual effort.

2to3 primarily handles syntactic and built-in function changes; it does not automatically convert all Python 2 libraries or APIs to their Python 3 equivalents. Manual refactoring is often required for dependencies. It may not always produce perfectly idiomatic Python 3 code. Some converted constructs might be suboptimal and benefit from further manual optimization. Complex uses of `unicode` vs. `bytes`, `long` integers, or specific metaclass patterns may require significant manual review and adjustment after `2to3` runs. The tool is designed for one-way conversion; there is no `3to2` counterpart.

2to3 works by applying a collection of modular transformation rules called 'fixers.' Each fixer addresses a specific change between Python 2 and Python 3, such as `print` statement conversion, `exec` statement to function, dictionary methods like `iteritems`, and changes to `raise` syntax. Users can select which fixers to run (or exclude) to fine-tune the conversion process.

To preview changes for a single file without writing:
`2to3 my_script.py`

To convert a directory of code and write changes, creating backups:
`2to3 -w my_project_dir/`

To convert and write without backups, only applying specific fixers:
`2to3 -w -n -f print -f xrange my_project_dir/`

The 2to3 utility was first introduced as a major component of the Python 3.0 release in 2008. Its primary goal was to ease the transition for developers and projects from the widely used Python 2.x series to the backward-incompatible Python 3.x series. Over the years, as Python 3 gained adoption and Python 2 approached its official end-of-life (January 1, 2020), the command's central role in new development diminished. However, it remains an indispensable tool for maintaining or porting older Python 2 codebases that are still in use or require migration to modern Python environments. Its development has focused on refining existing fixers and adding new ones to cover more transformation cases, though its active development has naturally slowed post-Python 2 EOL.

python(1), pip(1)