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

[hickford]

Reproduced from https://bitbucket.org/pypa/pypi/issue/149/package-pages-should-have-clear-pip

---

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.

---

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.

[ncoghlan]

Hmm, this is one potentially worth tackling in the existing PyPI code
base, rather than waiting for Warehouse. For example, we could have a
short block at the top of each page suggesting to try "pip install
" and pointing to packaging.python.org for assistance if that
fails for any reason.

[hickford]

What is Warehouse?

[kevinburke]

+1

I also see new users fail that step with "pip: command not found", a whole
bunch of copy failures followed by "Permission denied" (they needed to use
sudo or change permissions).

On Tuesday, June 3, 2014, Matt Hickford [email protected] wrote:

( Copied from
https://bitbucket.org/pypa/pypi/issue/149/package-pages-should-have-clear-pip
)

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.

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.

—
Reply to this email directly or view it on GitHub
#47.

Kevin Burke
phone: 925.271.7005 | kev.inburke.com

[alex]

Warehouse is the in-progress re-write of the codebase, to give us a better
base to build features on top of. You can see the preview deployment at
warehouse.python.org

On Tue, Jun 3, 2014 at 4:14 PM, Matt Hickford [email protected]
wrote:

What is Warehouse?

—
Reply to this email directly or view it on GitHub
#47 (comment)
.

"I disapprove of what you say, but I will defend to the death your right to
say it." -- Evelyn Beatrice Hall (summarizing Voltaire)
"The people's good is the highest law." -- Cicero
GPG Key fingerprint: 125F 5C67 DFE9 4084

[dstufft]

It wouldn't be particularly hard to do this in the current code base. We'd probably want to link to install instructions for pip for people who aren't using Python 3.4.

[hickford]

http://stackoverflow.com/q/21222114/284795

I downloaded it from: https://pypi.python.org/pypi/requests and now I have a .whl file. I've got Python 2.7 and 3.3 on Windows, so how do I install it so all the other Python scripts I run can use it?

[hickford]

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.

https://bitbucket.org/pypa/pypi/issues/149/package-pages-should-have-clear-pip#comment-21878779

[daenney]

I'm not entirely sure how people miss that pip can install directly from pypi. A lot of (prominent) projects have a pip install $projectname as part of their instructions which should at least hint at the fact that it fetches that project from somewhere itself much like any modern package manager.

[brainwane]

Thanks to everyone suggesting and discussing this!

The new PyPI does indeed include a prominent pip install direction at the top of a project page -- example. (One user has pointed out in pypi/warehouse#3006 that we need to be wary of situations where pip install will not Just Work. But that's another issue.)

Warehouse, the codebase behind the new PyPI, is available as a pre-production site at https://pypi.org, we're making steady progress on the developer roadmap thanks to funding from Mozilla's Open Source Support Program, and it's on its way to replacing the legacy PyPI site this year. We're currently seeking feedback from package maintainers, including via several IRC livechats/office hours this week, about what does or doesn't work for you in the new interface, and in the next few weeks we'll be doing so with the wider Python developer community.

I'm going to leave this issue open till we actually flip the switch and start redirecting people from pypi.python.org to pypi.org.

[hickford]

@brainwane Thanks for the links. The example looks good.

One idea for improvement: Npm package pages have a "how? learn more" link by the installation command. I think PyPI pages would be even clearer with a similar link, perhaps to https://packaging.python.org/tutorials/installing-packages/#installing-from-pypi

[brainwane]

I'm now going to close this issue since each package as displayed in Warehouse does include a pip install instruction at the top of the page. If people would like to add further suggestions for improving that aspect of the in-page instructions, I think pypi/warehouse#3006 and pypi/warehouse#1563 would be good places to add those suggestions. Thanks!