title: How to easily distribute Python software that has Python module dependencies? Frustrations in Python package installation on Unix
body: <p>My goal is to distribute a Python package that has several other widely used Python packages as dependencies.  My package depends on well written, Pypi-indexed packages like pandas, scipy and numpy, and specifies in the setup.py that certain versions or higher of these are needed, e.g. "numpy >= 1.5".</p>
  
  <p>I found that it's immensely frustrating and nearly impossible for Unix savvy users who are <em>not</em> experts in Python packaging (even if they know how to write Python) to install a package like mine, even when using what are supposed to be easy to use package managers.  I am wondering if there is an alternative to this painful process that someone can offer, or if my experience just reflects the very difficult current state of Python packaging and distribution.</p>
  
  <p>Suppose users download your package onto their system.  Most will try to install it "naively", using something like:</p>
  
  <pre><code>$ python setup.py install
  </code></pre>
  
  <p>Since if you google instructions on installing Python packages, this is usually what comes up.  This will fail for the vast majority of users, since most do not have root access on their Unix/Linux servers.  With more searching, they will discover the "--prefix" option and try:</p>
  
  <pre><code>$ python setup.py install --prefix=/some/local/dir
  </code></pre>
  
  <p>Since the users are not aware of the intricacies of Python packaging, they will pick an arbitrary directory as an argument to <code>--prefix</code>, e.g. <code>"~/software/mypackage/"</code>.  It will not be a cleanly curated directory where all other Python packages reside, because again, most users are not aware of these details.  If they install another package "myotherpackage", they might pass it <code>"~/software/myotherpackage"</code>, and you can imagine how down the road this will lead to frustrating hacking of <code>PYTHONPATH</code> and other complications.</p>
  
  <p>Continuing with the installation process, the call to <code>"setup.py install"</code> with <code>"--prefix"</code> will also fail once users try to use the package, even though it appeared to have been installed correctly, since one of the dependencies might be missing (e.g. pandas, scipy or numpy) and a package manager is not used.  They will try to install these packages individually.  Even if successful, the packages will inevitably not be in the <code>PYTHONPATH</code> due to the non-standard directories given to <code>"--prefix"</code> and patient users will dabble with modifications of their <code>PYTHONPATH</code> to get the dependencies to be visible.</p>
  
  <p>At this stage, users might be told by a Python savvy friend that they should use a package manager like <code>"easy_install"</code>, the mainstream manager, to install the software and have dependencies taken care of.  After installing <code>"easy_install"</code>, which might be difficult, they will try:</p>
  
  <pre><code>$ easy_install setup.py 
  </code></pre>
  
  <p>This too will fail, since users again do not typically have permission to install software globally on production Unix servers.  With more reading, they will learn about the <code>"--user"</code> option, and try:</p>
  
  <pre><code>$ easy_install setup.py --user 
  </code></pre>
  
  <p>They will get the error:</p>
  
  <pre><code>usage: easy_install [options] requirement_or_url ...
     or: easy_install --help
  
  error: option --user not recognized
  </code></pre>
  
  <p>They will be extremely puzzled why their <code>easy_install</code> does not have the <code>--user</code> option where there are clearly pages online describing the option.  They might try to upgrade their <code>easy_install</code> to the latest version and find that it still fails.</p>
  
  <p>If they continue and consult a Python packaging expert, they will discover that there are <strong>two versions</strong> of <code>easy_install</code>, both named "<code>easy_install"</code> so as to maximize confusion, but one part of "distribute" and the other part of "setuptools".  It happens to be that only the <code>"easy_install"</code> of <code>"distribute"</code> supports <code>"--user"</code> and the vast majority of servers/sys admins install <code>"setuptools"</code>'s <code>easy_install</code> and so local installation will not be possible.  Keep in mind that these distinctions between <code>"distribute"</code> and <code>"setuptools"</code> are meaningless and hard to understand for people who are not experts in Python package management.</p>
  
  <p>At this point, I would have lost 90% of even the most determined, savvy and patient users who try to install my software package -- and rightfully so!  They wanted to install a piece of software that happened to be written in Python, not to become experts in state of the art Python package distribution, and this is far too confusing and complex.  They will give up and be frustrated at the time wasted.</p>
  
  <p>The tiny minority of users who continue on and ask more Python experts will be told that they ought to use <code>pip/virtualenv</code> instead of <code>easy_install</code>.  Installing <code>pip</code> and <code>virtualenv</code> and figuring out how these tools work and how they are different from the conventional <code>"python setup.py"</code> or <code>"easy_install"</code> calls is in itself time consuming and difficult, and again too much to ask from users who just wanted to install a simple piece of Python software and use it. Even those who pursue this path will be confused as to whether whatever dependencies they installed with <code>easy_install</code> or <code>setup.py install --prefix</code> are still usable with <code>pip/virtualenv</code> or if everything needs to be reinstalled from scratch.</p>
  
  <p>This problem is exacerbated if one or more of the packages in question depends on installing a different version of Python than the one that is the default.  The difficulty of ensuring that your Python package manger is using the Python version you want it to, and that the required dependencies are installed in the relevant Python 2.x directory and not Python 2.y, will be so endlessly frustrating to users that they will certainly give up at that stage.</p>
  
  <p>Is there a simpler way to install Python software that doesn't require users to delve into all of these technical details of Python packages, paths and locations?  For example, I am not a big Java user, but I do use some Java tools occasionally, and don't recall ever having to worry about X and Y dependencies of the Java software I was installing, and I have no clue how Java package managing works (and I'm happy that I don't -- I just wanted to use a tool that happened to be written in Java.)  My recollection is that if you download a Jar, you just get it and it tends to work.  </p>
  
  <p>Is there an equivalent for Python?  A way to distribute software in a way that doesn't depend on users having to chase down all these dependencies and versions?  A way to perhaps compile all the relevant packages into something self-contained that can just be downloaded and used as a binary?</p>
  
  <p>I would like to emphasize that this frustration happens even with the narrow goal of distributing a package to savvy Unix users, which makes the problem simpler by not worrying about cross platform issues, etc.  I assume that the users are Unix savvy, and might even know Python, but just aren't aware (and don't want to be made aware) about the ins and outs of Python packaging and the myriad of internal complications/rivalries of different package managers.  A disturbing feature of this issue is that it happens even when all of your Python package dependencies are well-known, well-written and well-maintained Pypi-available packages like Pandas, Scipy and Numpy.  It's not like I was relying on some obscure dependencies that are not properly formed packages: rather, I was using the most mainstream packages that many might rely on.</p>
  
  <p>Any help or advice on this will be greatly appreciated.  I think Python is a great language with great libraries, but I find it virtually impossible to distribute the software I write in it (once it has dependencies) in a way that is easy for people to install locally and just run.  I would like to clarify that the software I'm writing is not a Python library for programmatic use, but software that has executable scripts that users run as individual programs. Thanks.</p>