TODO I’m mentioning The Python Package Index (PyPI) 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 The Python Package Index (PyPI) first. The other options are:
We will cover the The Python Package Index (PyPI) later in the documentation.
When using the Pip Installs Python (Pip) application, how does it know what to install when you run pip install Markdown? By default, it checks the The Python Package Index (PyPI) 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:
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
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.
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.