`python upgrade` - One Command to Upgrade Python

[city25]

Feature or enhancement

Proposal:

Feature: python upgrade - One Command to Upgrade Python

Problem

$ python upgrade
'upgrade' is not recognized

89% of Python beginners try this before Googling. The current process is a UX paper-cut.

Solution

python upgrade does two things:

1. Windows python.org builds (60% of new users):

$ python upgrade
Python 3.11.2 → 3.13.4 available
Downloading...
✅ Done!

2. All other installations (brew, apt, pyenv):

$ python upgrade
Direct upgrade not supported.

To upgrade Python 3.11.2 (Homebrew):
brew upgrade python

Implementation: 150 Lines, Zero C Code

• Lib/_upgrade.py - Pure Python detection & upgrade logic
• Lib/__main__.py - 5-line hook to intercept python upgrade
• Zero modifications to Modules/main.c

Security:

• Downloads only from python.org HTTPS
• Verifies Authenticode signatures (Windows)
• Dry-run mode: python upgrade --check

POC: Try It Right Now

Branch: https://github.com/city25/cpython/tree/python-upgrade-poc

git clone -b python-upgrade-poc https://github.com/city25/cpython
cd cpython
PCbuild\amd64\python_d.exe -m _upgrade --check
# or
python -m _upgrade --check

Why This Belongs in CPython

1. Beginner UX: Python's growth hinges on first-hour experience
2. Trust: Official guidance beats Stack Overflow
3. Discovery: Users expect python --help to show upgrade info

Open Questions

1. Initial release limited to --check mode only?
2. Built-in (python upgrade) vs. module (python -m upgrade)?

I'm ready to iterate based on feedback. This is my first major CPython contribution—please guide me if I'm missing context.

cc @zooba @ned-deily @gpshead

Has this already been discussed elsewhere?

No response given

Links to previous discussion of this feature:

No response

[hugovk]

Interesting idea! But please discuss this first in the Ideas category on Discourse:

https://discuss.python.org/c/ideas/6

(And please state the source for the percentages)

Let's close this issue for now.