1. PyPA
  2. Python Packaging Authority Projects
  3. pypi


Issue #149 new

Package pages should have clear "pip install" instructions near top of page

Mirth Hickford
created an issue

Take a look at any package page on the Ruby gems website (eg. https://rubygems.org/gems/rails ). At the top of the page, it has the installation instructions in large friendly letters (eg. gem install rails). Similarly, on any Nodejs package page (eg. https://www.npmjs.org/package/express ) the installation instructions are near the top and very clear (eg. npm install express)

However, browse to a package page on Python's package index PyPI (eg. https://pypi.python.org/pypi/lxml/3.3.5 ) and there's no installation instructions at all! There should be clear instructions at the top of the page (eg. pip install lxml. Pip is the Python package manager and the easiest way to install packages.).

Don't underestimate the importance of clear instructions. They would be extremely helpful, particularly to new users. There's a huge amount of confusion about how to install Python packages, as evidenced by popular search queries and StackOverflow questions. This is the long shadow of Python's history of shipping without a package manager.

Now Python (from version 3.4) ships with the package manager Pip, packages can be installed easily, but users need to be educated how.

If you doubt the problem, observe that a number of high-ranking web pages encourage the use of the obsolete and lacking easy_install script. And that the deprecated packaging library distribute still receives upwards of a million downloads per month. The confusion around packages is a real barrier to new users learning Python.

Comments (4)

  1. Mirth Hickford reporter

    I'd argue that the current content of PyPI package pages is actually counter-helpful. See, for example https://pypi.python.org/pypi/Jinja2 . There's no instruction to pip install the package (agreed to be best way to install packages). There's no instructions at all. The user's eyes light instead on the download link at the bottom page. This saves a .tar.gz file. For many Windows users, extracting this archive is challenge enough (remember, we recommend Python to people who've never programmed before). After that, it's still not obvious. The most reasonable action is to double-click setup.py but that just opens a command line window that dissappears again. What to do? The persevering user might go search the web and deduce to run python setup.py install, but some will give up before that. Perhaps they'll write their software in javascript.

    The easiest way to install the package would have been pip install, but the PyPI page never mentioned it, and instead pointed the user download another more difficult path.

  2. Eric Moyer

    To speak to the confusion, I didn't realize until today that pip could download from pypi - I always used it from the install directory of a tarball.

    Also, the directions should take into account when there is nothing to download. I looked at https://pypi.python.org/pypi/pywin32/214 for quite a while and didn't realize that there was nothing to download.

  3. Log in to comment