Repository navigation
Add install instructions when dependencies are missing #2569
Description
Right now:
$ ipython notebook
[... snip]
raise ImportError("%s requires pyzmq >= %s"%(module, minimum_version))
ImportError: IPython.zmq requires pyzmq >= 2.1.4
This is not super helpful. More helpful would be to have a message like:
$ ipython notebook
You're missing some dependencies required to run the IPython notebook. You can
install them by doing:
easy_install ipython[zmq,qtconsole,notebook,test]
Or see read this for more information: http://ipython.org/ipython-doc/dev/install/install.html#installnotebook
Bonus points if there was a PyPI metapackage which just pulls in the right dependencies, such as ipython-notebook.
Activity
takluyver commentedon Nov 12, 2012
If the user doesn't have pyzmq installed, there's a good chance that they
don't have zmq itself either, which easy_install can't resolve (at least,
not for all systems). Telling people to use easy_install also ignores all
the different ways people like to install stuff - apt, macports, pypm, exe
installers, and so on.
So I think it's reasonable for the error to describe what's required, and
leave getting that up to the user.
On 12 November 2012 17:05, Andrey Petrov notifications@github.com wrote:
shazow commentedon Nov 12, 2012
@dwf mentioned that there's some magic in pyzmq to statically compile and link zmq if it's not available.
Either way, proper instructions for all of the dependencies are far more useful than a one-at-a-time exception stack trace.
rkern commentedon Nov 12, 2012
Providing a link to the PyPI page for pyzmq seems reasonable. That will have the most up to date installation instructions and won't disappear. Providing installation instructions in an exception message (either the raw exception message or the friendlier message that gets printed when caught) is not wise.
shazow commentedon Nov 12, 2012
@rkern Why is it not wise?
dwf commentedon Nov 12, 2012
@shazow I'm guessing @rkern (amazing new avatar by the way Robert) is worried about bit rot. Putting user-facing documentation in strings may be problematic because nobody will remember to update that when the docs are reorganized. Greg's old maxim about "if the same information is copied in two places it will be always be wrong in at least one" applies, especially if it's an obscure place.
shazow commentedon Nov 12, 2012
If IPython wants wide adoption, we can't expect every user to read the docs (let alone multiple doc pages—how to run notebook, how to install dependencies) before trying to run it and giving up thinking it's broken.
fperez commentedon Nov 12, 2012
I think a printed message with pypi links to the main packages is a good balance: the only thing we're copying is the name of our dependencies, and no more. We refer the user to the package page, and it's up to the maintainer of those pages to update them as their package evolves.
takluyver commentedon Nov 12, 2012
People messing around with easy_install and pip is not going to get us to 'wide adoption' - there are far too many problems there, and it's beyond our scope to fix them. There are better installation methods we recommend, including:
shazow commentedon Nov 12, 2012
I can buy the "we should go full-force with distro package managers" argument, but then this needs to be the recommended installation method rather than easy_install.
For what it's worth, running
pip install ipython[zmq,qtconsole,notebook,test]on my OSX was all I had to do to get it working. I suspect the same thing would be true on my Linux box. That's pretty swell and it would be a shame to bury this fact with more complicated instructions.takluyver commentedon Nov 12, 2012
Well, it's tricky to recommend distro package managers, because they have different commands, and call the package different things (e.g. macports packages include the Python version, so you install
py32-ipythonor similar). I'm starting to build up this installation page for the Scipy stack, which will give the relevant instructions for different package managers.takluyver commentedon Nov 12, 2012
Of course, it's great when the simple method does work. But there's a significant fraction of cases where it won't, so we can't offer it as something that works for everyone. But for what it's worth, the 'Quickstart' section of the installation instructions does give that simple method.
shazow commentedon Nov 12, 2012
@takluyver Right, my original proposal was to include a brief version of 'Quickstart' as a printed error message, with a link.
takluyver commentedon Nov 12, 2012
The difference is that in the docs, we have space to expand on the details,
and we can easily update it later (I'm assuming most people consult the
docs online). Putting the command in an error message creates an
expectation that it will just work for everyone.
As others have said, a link to the pyzmq PyPI page would be a good
compromise.
On 12 November 2012 18:16, Andrey Petrov notifications@github.com wrote:
dwf commentedon Nov 12, 2012
Apparently this has been ditched on the current scipy.github.com, but I created this reference table (bottom of the page) to at least ease the process of locating the proper distro package. Maybe something similar with a similar caveat emptor.
takluyver commentedon Nov 12, 2012
@dwf: If you're interested, could you help with writing the installation commands for other distros, like the one on that page for Debian-based distros? I started the installation page from scratch to deal with installing all of the core scipy stack, because the existing instructions were just for numpy and the scipy library. Pull requests welcome at https://github.com/scipy/scipy.org-new