pip --force-reinstall

Problem

Currently, when pip install [package-name] --force-reinstall is executed, instead of reinstalling the package at the version previously installed, pip installs the package at the newest version available.

i.e. pip install [package name] --force-reinstall acts as pip [package name] --upgrade

We want to find out if users understand (or desire) this implicit behaviour.

More information can be found on this GitHub issue.

Skip to recommendations

Research

To help us understand what users want from the --force-reinstall option, we launched a survey with the following scenario:

You have the requests package and its dependencies installed:

requests==2.22.0
asgiref==3.2.10
certifi==2020.6.20
chardet==3.0.4
Django==3.1
idna==2.8
pytz==2020.1
sqlparse==0.3.1
urllib3==1.25.10

You run ‘pip install requests --force-reinstall’. What should happen?

Respondents could choose from one of the following options:

  • pip reinstalls the same version of requests. pip does not reinstall request’s dependencies.

  • pip reinstalls requests and its dependencies, updating all these packages to the latest compatible versions

  • pip reinstalls requests and its dependencies, keeping every package on the same version

  • pip reinstalls requests, updating it to the latest version. pip updates request’s dependencies where necessary to support the newer version.

  • I don’t know what pip should do

  • I don’t understand the question

  • Other (allows respondent to provide their own answer)

We also asked how useful pip --force-reinstall is, and how often it is used.

Results

In total we received 190 responses to our survey, with 186 people telling us what pip should do when the --force-reinstall option is executed.

pie chart with survey results

  • 31.7% (59/186) of respondents said that pip should reinstall requests and its dependencies, keeping every package on the same version

  • 28% (52/186) of respondents said that pip should reinstall requests, updating it to the latest version, with pip updating request’s dependencies where necessary to support the newer version.

  • 15.6% (29/186) of respondents said that pip should reinstall requests and its dependencies, updating all these packages to the latest compatible versions

  • 14% (26/186) of respondents said that pip should reinstall the same version of requests, and not reinstall request’s dependencies

If we group responses into “upgrade” or “do not upgrade” (ignoring responses that could not be grouped), we find:

  • 46.32% (88/186) of respondents thought that pip should install the same version of requests - i.e. that --force-reinstall should not implicitly upgrade

  • 43.16% (82/186) of respondents thought that pip should upgrade requests to the latest version - i.e that --force-reinstall should implicitly upgrade

Most respondents use --force-reinstall “almost never” (65.6%):

screenshot of survey question of how often users use --force-reinstall bar chart of how often users use --force-reinstall

Amongst respondents who said they use --force-resinstall often or very often:

  • 54.54% (6/11) of respondents thought that pip should install the same version of requests - i.e. that --force-reinstall should not implicitly upgrade

  • 45.45% (5/11) of respondents thought that pip should upgrade requests to the latest version - i.e that --force-reinstall should implicitly upgrade

Respondents find --force-reinstall less useful than useful:

screenshot of survey question of how useful users find --force-reinstall bar chart of how useful users find --force-reinstall

Amongst respondents who said they find --force-resinstall useful or very useful:

  • 38.46% (20/52) of respondents thought that pip should install the same version of requests - i.e. that --force-reinstall should not implicitly upgrade

  • 50% (26/52) of respondents thought that pip should upgrade requests to the latest version - i.e that --force-reinstall should implicitly upgrade

Recommendations

Given that this option is not regularly used and not strongly rated as useful, we recommend that the development team consider removing --force-reinstall should they wish to reduce maintenance overhead.

In this case, we recommend showing the following message when a user tries to use --force-reinstall:

Error: the pip install --force-reinstall option no longer exists. Use pip uninstall then pip install to replace up-to-date packages, or pip install --upgrade to update your packages to the latest available versions.

Should the pip development team wish to keep --force-resintall, we recommend maintaining the current (implicit upgrade) behaviour, as pip’s users have not expressed a clear preference for a different behaviour.

In this case, we recommend upgrading the help text to be more explicit:

Old help text:

Reinstall all packages even if they are already up-to-date.

New help text:

Reinstall package(s), and their dependencies, even if they are already up-to-date. Where package(s) are not up-to-date, upgrade these to the latest version (unless version specifiers are used).