Documentation doesn't explain how to upgrade Python version

[JDLH]

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": {}
}

[J-M0]

While I agree that there should be some clarity, the discussion you reference is incorrect that the --python option will update the Python version. To upgrade a project from one Python version to another is simple though:

1. Run pipenv --rm to destroy the existing virtualenv
2. Edit the python_version line of your Pipfile to the desired Python version
3. Run pipenv update to create the new virtualenv and update your dependencies

Also, as a general rule of thumb you should never edit Pipfile.lock. It is automatically generated and updated by various pipenv commands and any changes you make would be lost.

[JDLH]

I agree that there should be some clarity… Great! Let's improve the documentation to add that clarity.

…the discussion you reference [#2482, Originally posted by @andrewm4894 in https://github.com/pypa/pipenv/issues/2482#issuecomment-422366569] is incorrect that the --python option will update the Python version… Great! Let's improve the documentation so that in a future discussion people can point to the correct answer.

… To upgrade a project from one Python version to another is simple… Great! That 3-step list looks like the starting point for improving the documentation.

Where I would like to see the documentation improved is in docs/basics.rst, after section Example Pipenv Upgrade Workflow and before section Importing from requirements.txt, a new section entitled something like, Example Python version upgrade workflow. It would have the 3-step list above.

There may be other locations that would be a better way to add this information to the documentation. I am open to suggestion. That is just where I looked for it first.

Would it be helpful for me to propose such a PR?

[timothylimyl]

@JDLH , totally agree that there should be an official procedure for Python version change which is recommended by the developers! For example, I am not too certain on whether does doing these steps will end up updating other packages or breaking anything:

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

It is compulsory that you need to remove your virtual environment entirely (pipenv rm) and reinstall every package each time you want to upgrade/downgrade python or can you add an extra step (step 3) to run pipenv upgrade?

Also, I think it will be great to have a feature that edits the Pipfile directly when pipenv --python X+1 is run in a virtual environment with a different python version. Doesn't pipenv upgrade already does it for all other packages?

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