============== Using Packages ============== Finding Packages ================ .. note:: TODO I'm mentioning :ref:`pypi_info` everywhere. Should probably move this up in the documentation instead of explaining it over and over. How does one find a package. Well, the simple answer is to check :ref:`pypi_info` first. The other options are: - To do a simple web search with google.com, yahoo, etc. - Ask around the python community using :term:`IRC` We will cover the :ref:`pypi_info` later in the documentation. Installing from other sources ============================= When using the :ref:`pip_info` application, how does it know what to install when you run ``pip install Markdown``? By default, it checks the :ref:`pypi_info` for a package of that name. In this case, it found one; but what if you want to install a package that hasn't been uploaded to PyPI? You have several options: - `Installing from a tarball`_ - `Installing from a Version Control System (VCS)`_ - `Add URLs to search for links`_ .. index:: tarball; install Installing from a tarball ------------------------- You can install directly from a tarball or zip file, as long as there is a working ``setup.py`` file in the root directory of the unzipped contents:: $ pip install path/to/mypackage.tgz You can also install from a tarball/zip file over the network:: $ pip install http://dist.repoze.org/PIL-1.1.6.tar.gz Installing from a Version Control System (VCS) ---------------------------------------------- Using the ``--editable`` or ``-e`` option, pip has the capability to install directly from a version control repository (it currently supports Subversion, Mercurial, Git, and Bazaar):: $ pip install -e svn+http://svn.colorstudy.com/INITools/trunk#egg=initools-dev This option shells out to the command-line client for each respective VCS, so you must have the VCS installed on your system. The repo URL must begin with ``svn+`` (or ``hg+``, ``git+``, or ``bzr+``) and end with ``#egg=packagename``; otherwise, pip supports the same URL formats and wire protocols supported by the VCS itself. Pip will checkout the source repo into a ``src/`` directory inside the virtualenv (i.e. ``pip_test_env/src/initools-dev``), and then run ``python setup.py develop`` in that source repo. This "links" the code directly from the repo into the virtualenv's ``site-packages`` directory (by adding the repo directory into ``easy-install.pth``), so changes you make in the source checkout are effective immediately. If you already have a local VCS checkout you want to keep using, you can just use ``pip install -e path/to/repo`` to install it "editable" in the same way. Add URLs to search for links ---------------------------- You can use the ``-f`` or ``--find-links`` option to add another URL pip should search for links to the package. If you dump some package tarballs in a webserver directory and turn on automatic indexing, you can point pip at that index page and install any of those packages, assuming you named the files in the pattern ``packagename-version.ext``. For example, if you upload a tarball ``MyApp-1.0.tgz`` to a ``my-packages`` directory on your webserver, and make sure indexing is on for that directory, you can run:: $ pip install MyApp -f http://www.example.com/my-packages/ .. index:: single: package index; creating single: package index; chishop Running your own package index ============================== If you want more of the features provided by PyPI (including the ability to upload packages with ``python setup.py sdist upload``), you can run software such as `chishop`_, which implements the PyPI API, on your own server. Then you can use pip's ``-i`` (or ``--index-url``) or ``--extra-index-url`` options to point it at your index. For instance, if you set up your own index at http://www.example.com/chishop/, you might run:: $ pip install MyPrivateApp -i http://www.example.com/chishop/simple/ If you use ``-i`` pip won't check PyPI, only the index you provide. If you are installing multiple packages at once, some from your index and some from PyPI, you may want to use ``--extra-index-url`` instead, so pip will check both indexes. .. _chishop: http://github.com/ask/chishop