Documentation doesn't explain how to upgrade Python version

Is your feature request related to a problem? Please describe.

I have a pipenv for my project, using Python version X. I want to move my project to Python version X+1 (or X+0.1). The documentation does not explain how to do this. The obvious command, pipenv python --X+1, results in a state with a warnings.

Describe the solution you’d like

The documentation should have a section, “How to upgrade the Python version”. It should lay out the steps one must follow to upgrade the Python interpreter.

This section would fit well in a section after https://pipenv.pypa.io/en/latest/basics/#example-pipenv-upgrade-workflow. If there are more complicated details, they should perhaps be in a section under https://pipenv.pypa.io/en/latest/advanced/ .

Describe alternatives you’ve considered

Issue #2482 asserts that pipenv --python 3.6 should be enough to upgrade the Python version and the reference to the Python version in Pipfile and Pipfile.lock. However, the discussion makes it clear that this is not what happens, nor is it what the developers believe should happen.

It is not clear to me if it is enough to:

1. Edit Pipfile, changing old Python version X to X+1
2. run pipenv --python X+1

Should one have to run pipenv --rm? I am not sure.

Should one edit Pipfile.lock in addition to Pipfile? I am not sure.

Additional context

Observed when upgrading a Python 2.7 project to Python 3.8, on macOS 10.13.6 High Sierra. From the discussion, it seems the procedure to upgrade the Python version is general for all version upgrades.

---

$ pipenv --support

Pipenv version: '2020.8.13'

Pipenv location: '/opt/local/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/pipenv'

Python location: '/opt/local/Library/Frameworks/Python.framework/Versions/3.8/bin/python3.8'

Python installations found:

• 3.8.7: /Users/myuserid/.local/share/virtualenvs/MyProject-QGqwYDDx/bin/python3
• 3.8.7: /Users/myuserid/.local/share/virtualenvs/MyProject-QGqwYDDx/bin/python3.8
• 3.8.7: /Users/myuserid/.local/share/virtualenvs/MyProject-QGqwYDDx/bin/python3
• 3.8.7: /Users/myuserid/.local/share/virtualenvs/MyProject-QGqwYDDx/bin/python3.8
• 3.8.7: /opt/local/bin/python3.8
• 3.7.9: /opt/local/Library/Frameworks/Python.framework/Versions/Current/bin/python3
• 3.7.9: /opt/local/Library/Frameworks/Python.framework/Versions/Current/bin/python3.7m
• 3.7.9: /opt/local/Library/Frameworks/Python.framework/Versions/Current/bin/python3.7
• 3.7.9: /opt/local/bin/python3
• 3.7.9: /opt/local/bin/python3.7m
• 3.7.9: /opt/local/bin/python3.7
• 3.6.12: /opt/local/bin/python3.6
• 3.6.12: /opt/local/bin/python3.6m
• 3.3.7: /opt/local/bin/python3.3
• 2.7.18: /opt/local/bin/python2
• 2.7.18: /opt/local/bin/python2.7
• 2.7.16: /usr/bin/python2.7
• 2.5.0: /usr/local/bin/python2.5

PEP 508 Information:

{'implementation_name': 'cpython',
 'implementation_version': '3.8.7',
 'os_name': 'posix',
 'platform_machine': 'x86_64',
 'platform_python_implementation': 'CPython',
 'platform_release': '17.7.0',
 'platform_system': 'Darwin',
 'platform_version': 'Darwin Kernel Version 17.7.0: Fri Oct 30 13:34:27 PDT '
                     '2020; root:xnu-4570.71.82.8~1/RELEASE_X86_64',
 'python_full_version': '3.8.7',
 'python_version': '3.8',
 'sys_platform': 'darwin'}

System environment variables:

• TMPDIR
• XPC_FLAGS
• Apple_PubSub_Socket_Render
• TERM
• LANG
• SSH_AUTH_SOCK
• DISPLAY
• SECURITYSESSIONID
• XPC_SERVICE_NAME
• TERM_PROGRAM
• TERM_PROGRAM_VERSION
• TERM_SESSION_ID
• SHELL
• HOME
• LOGNAME
• USER
• PATH
• SHLVL
• PWD
• OLDPWD
• MANPATH
• EDITOR
• DBUS_SESSION_BUS_ADDRESS
• PYTHONPATH
• DJANGO_SETTINGS_MODULE
• PERL_MB_OPT
• PERL_MM_OPT
• PGDATA
• W
• SSH_ENV
• SSH_AGENT_PID
• __CF_USER_TEXT_ENCODING
• PIP_DISABLE_PIP_VERSION_CHECK
• PYTHONDONTWRITEBYTECODE
• PIP_PYTHON_PATH
• PIPENV_ACTIVE
• VIRTUAL_ENV
• PS1
• _
• PIP_SHIMS_BASE_MODULE
• PYTHONFINDER_IGNORE_UNSUPPORTED

Pipenv–specific environment variables:

• PIPENV_ACTIVE: 1

Debug–specific environment variables:

• PATH: /Users/myuserid/.local/share/virtualenvs/MyProject-QGqwYDDx/bin:/opt/local/Library/Frameworks/Python.framework/Versions/Current/bin:/Users/myuserid/bin/:/opt/local/bin:/opt/local/sbin:/opt/local/Library/Frameworks/Python.framework/Versions/Current/bin:/Users/myuserid/bin/:/opt/local/bin:/opt/local/sbin:/opt/local/bin:/opt/local/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin:/Applications/Wireshark.app/Contents/MacOS:/opt/local/lib/postgresql94/bin/:/opt/local/lib/postgresql94/bin/
• SHELL: /bin/zsh
• EDITOR: /usr/bin/pico
• LANG: en_CA.UTF-8
• PWD: /Users/myuserid/workspace/MyProject/src
• VIRTUAL_ENV: /Users/myuserid/.local/share/virtualenvs/MyProject-QGqwYDDx

---

Contents of Pipfile (‘/Users/myuserid/workspace/MyProject/Pipfile’):

[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

[dev-packages]

[packages]
pytz = "*"

[requires]
python_version = "3.8"

Contents of Pipfile.lock (‘/Users/myuserid/workspace/MyProject/Pipfile.lock’):

{
    "_meta": {
        "hash": {
            "sha256": "6bb63ee956e08f88ca14bbe22f144bc6378af47f14deb5139b778e3a321d4130"
        },
        "pipfile-spec": 6,
        "requires": {
            "python_version": "3.8"
        },
        "sources": [
            {
                "name": "pypi",
                "url": "https://pypi.org/simple",
                "verify_ssl": true
            }
        ]
    },
    "default": {
        "pytz": {
            "hashes": [
                "sha256:16962c5fb8db4a8f63a26646d8886e9d769b6c511543557bc84e9569fb9a9cb4",
                "sha256:180befebb1927b16f6b57101720075a984c019ac16b1b7575673bea42c6c3da5"
            ],
            "index": "pypi",
            "version": "==2020.5"
        }
    },
    "develop": {}
}

[matteius]

@JDLH I know your offer to help with a PR improving the documentation is a little old by now, but if you are still interested in doing so I think it would be a reasonable improvement. Would be happy to try and help push it across the line.

[justasojourner]

Hi @matteius, are you still interested in this additional documentation? I’m looking to upgrade a project from Python 3.9 to 3.10 (to get structural pattern matching) so I was looking for the optimum/correct/developer specified way to do this, and I saw that the documentation is not there still.

Also, just as an observation, I downloaded the repo to have a look at the existing documentation — there are some challenges I see.