pyupgrade

Warnings

• gotcha pyupgrade does not natively process directories recursively. Users commonly combine it with `find` or use `pre-commit` to apply it across an entire codebase. Alternatively, `pyupgrade-directories` is a separate tool available for this purpose.
  Fix: Use `find . -name '*.py' -exec pyupgrade --py3N-plus {} +` for recursive application, or integrate it as a `pre-commit` hook (e.g., `pre-commit run pyupgrade --all-files`).
• gotcha By default, `pyupgrade` exits with a non-zero status code (1) if it makes any changes. This can cause CI pipelines to fail. Use the `--exit-zero-even-if-changed` flag to ensure a successful exit code even when changes are applied.
  Fix: Add `--exit-zero-even-if-changed` to your pyupgrade command or pre-commit hook configuration.
• gotcha The `--pyN-plus` flag (e.g., `--py38-plus`, `--py311-plus`) is crucial to specify the minimum Python version whose syntax rules should be applied. Failing to specify it, or choosing a version too low, might prevent desired modernizations or apply changes unsuitable for your actual target runtime environment. `pyupgrade` defaults to generic Python 3 if no specific version is provided.
  Fix: Always explicitly provide the `--pyN-plus` flag corresponding to the minimum Python version you intend to support (e.g., `--py38-plus` for Python 3.8 and newer).
• gotcha If you are already using `ruff` with the `UP` (pyupgrade) rules enabled, a separate `pyupgrade` pre-commit hook or standalone run might be redundant, as `ruff` can perform many of the same modernizations.
  Fix: Review your `ruff` configuration (e.g., in `pyproject.toml`) for `select = ['UP']` to avoid duplicate tooling. `ruff --fix` often handles these upgrades.
• gotcha `pyupgrade` may convert `typing.Type` to `builtins.type`. While often interchangeable, in strict type-checking contexts (e.g., with Pyright), these are distinct and can lead to type errors if `typing.Type` was intended as a generic type. This can be problematic if `Type` is used without a type argument.
  Fix: If you encounter issues with type checkers, use the `--keep-runtime-typing` flag to prevent these specific typing rewrites. Ensure `typing.Type` is always used with a type argument (e.g., `Type[int]`) if that's the intended meaning.
• gotcha pyupgrade focuses solely on syntax upgrades. It does not perform semantic or logical checks. After running `pyupgrade`, manual inspection, testing, and linting are still crucial to ensure the upgraded code remains logically correct and compatible with third-party libraries.
  Fix: Always run your test suite and a linter (e.g., `ruff`, `flake8`) after applying `pyupgrade` to catch any regressions or new issues.

Install

• pip install pyupgrade Install via pip

Quickstart

To quickly upgrade a Python file, first save your code, then run `pyupgrade` from your terminal, specifying the target Python version using a `--pyN-plus` flag. This example updates `my_module.py` to Python 3.8+ syntax, converting old string formatting, removing redundant `(object)` inheritance, and updating type hints.

# my_module.py
import os
from typing import List

def old_function(name):
    print("Hello, %s!" % name)

class OldClass(object):
    def __init__(self, value):
        self.value = value

def process_items(items: List[int]) -> List[int]:
    return [x * 2 for x in items]

# Run pyupgrade from the command line:
# pyupgrade --py38-plus my_module.py
# This will update the file in place to, for example, use f-strings and remove object inheritance.