Using pip instead of the Linux distributions package manager is considered bad practice because:

• may end up having two version of a package installed which can trigger problems. (Packages installed by pip are not visible to apt and vice-versa.)
• some pip packages have binary components. Some versions of these components may be not compatible to other binaries installed on the machine. This means only some versions of such pip packages are compatible with a specific distro.

The best policy is to use pip with virtualenv, and use the package manager of the distribution otherwise.

Maybe the best would be to start using virtualenv and start shipping reguirements.txt files.

While using virtualenv with a requirements.txt with recommended hard-coded versions is definitely best solution it may come at the expense of user experience.

While this is being considered, for Ubuntu or other fixed-release type distributions, using the package manager may not be a better choice than pip.

• Ubuntu has a fixed release schedule with only security updates being provided to their packages. This can cause significantly varied experience based on which version of Ubuntu a user runs the command on.
• If an upgrade or downgrade is required, which falls outside of the package version scope of the current release, the user workflow will significantly be affected.
• pip allows distribution from source, which will compile the dependencies and couple them to the enviroment provided by the machine. Package manager can easily result in a dependency resolution deadlock when requesting a version of a package which is incompatible with the others.
• There is already guidance for users to use pip on windows. It may be recommenced to keep instructions as consistent as possible.
• pip is is using setup-tools and is highly portable. In most cases even if a package is installed by the package manager, pip will be able to install it in a different location and update the enviroment accordingly.

What's wrong with virtualenv? How does it hurt the user experience?

I will investigate adding instructions for using virtualenv. My feeling is that some users will consider it too complicated to set up just to build the project though. Maybe we could provide instructions for both alternatives?

I think we shall discuss the issue internally with the team first.