pyupgrade

library3.21.2pypypiunverified

pyupgrade is an active Python tool (version 3.21.2) designed to automatically upgrade code syntax for newer language versions. It streamlines the process of adopting modern Python features, improving code readability and efficiency. It's primarily used as a command-line utility or integrated into development workflows via pre-commit hooks, with new versions released continuously to support the latest Python syntax.

devops testing

pip install pyupgrade

github ↗package ↗

INSTALL

IMPORT

SIG · PYUPGRADE

pyupgrade

devopspythonv3.21.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.

pyupgrade --version

Debug

Known issues

gotchapyupgrade 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`).

affects: All versions

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

affects: All versions

gotchaThe `--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).

affects: All versions

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

affects: All versions where Ruff is used with UP rules

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.

affects: All versions (especially with Python >=3.9, PEP 585/604)

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

affects: All versions

Errors

Common errors & fixes

pyupgrade: failed to parse <file>: invalid syntax (<unknown>, line X)

The Python file you are trying to upgrade contains a syntax error that prevents pyupgrade from parsing it.

fix

Correct the existing syntax errors in the specified file before running `pyupgrade`.

pyupgrade: error: unrecognized arguments: <argument>

You have passed an invalid, misspelled, or unsupported command-line argument to the `pyupgrade` command.

fix

Check the `pyupgrade` documentation or run `pyupgrade --help` to verify the correct arguments and their syntax, then correct the argument.

ModuleNotFoundError: No module named 'pyupgrade'

The `pyupgrade` package is not installed in your current Python environment, or the environment where the command is being executed (e.g., a pre-commit hook's isolated environment).

fix

Install `pyupgrade` using `pip install pyupgrade`. If using `pre-commit`, ensure your `.pre-commit-config.yaml` is correctly configured with `repo: https://github.com/asottile/pyupgrade`.

PermissionError: [Errno 13] Permission denied: '/path/to/file.py'

`pyupgrade` attempted to modify a file but encountered a permission error, meaning the user running the command does not have write access to that file.

fix

Ensure that the user executing `pyupgrade` has write permissions for the target file(s), or change the file permissions using `chmod`.

Upgrade

Version history

3.21.2latest on PyPI · released Nov 19, 2025

Audit

Dependencies

Pythonrequiredpyupgrade itself requires Python >=3.10 to run, although it can transform code for earlier target Python versions.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/asottile/pyupgrade ↗

packagehttps://pypi.org/project/pyupgrade/ ↗