LinuxCommandLibrary

2to3

Convert Python 2 code to Python 3

TLDR

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

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

Convert a Python 2 file to Python 3
$ 2to3 --write [path/to/file.py]
copy

Convert specific Python 2 language features to Python 3
$ 2to3 --write [path/to/file.py] --fix [raw_input] --fix [print]
copy

Convert all Python 2 language features except the specified ones to Python 3
$ 2to3 --write [path/to/file.py] --nofix [has_key] --nofix [isinstance]
copy

List all available language features that can be converted from Python 2 to Python 3
$ 2to3 --list-fixes
copy

Convert all Python 2 files in a directory to Python 3
$ 2to3 --output-dir [path/to/python3_directory] --write-unchanged-files --nobackups [path/to/python2_directory]
copy

Run 2to3 with multiple threads
$ 2to3 --processes [4] --output-dir [path/to/python3_directory] --write --nobackups --no-diff [path/to/python2_directory]
copy

SYNOPSIS

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 ...

PARAMETERS

-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

, --output-dir
    Write converted files to a specified output directory instead of overwriting original files. Directory must exist.

-f , --fix
    Only run specified fixers. This option can be used multiple times to specify several fixers.

-x , --nofix
    Do not run specified fixers. This option can be used multiple times to exclude several fixers.

--add-fixer
    Add a custom fixer from a specified path. This allows using user-defined transformation rules.

--list-fixers
    List all available fixers. Useful for understanding what transformations 2to3 can perform.

--diffs
    Always show diffs of the changes, even when writing files (with `-w`).

--no-diffs
    Do not show diffs of the changes, even when not writing files.

-p , --processes
    Run `num` fixers in parallel. Useful for speeding up conversion of large codebases.

-v, --verbose
    Print more information about the conversion process, including which fixers are being applied.

--version
    Show program's version number and exit.

-h, --help
    Show this help message and exit.

DESCRIPTION

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.

CAVEATS

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.

FIXERS

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.

TYPICAL USAGE

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/`

HISTORY

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.

SEE ALSO

python(1), pip(1)

Copied to clipboard