mirror of https://github.com/pypa/pip
207 lines
6.7 KiB
Plaintext
207 lines
6.7 KiB
Plaintext
=====
|
|
Usage
|
|
=====
|
|
|
|
Install packages
|
|
----------------
|
|
|
|
The simplest way to install a package is by specifying its name::
|
|
|
|
$ pip install SomePackage
|
|
|
|
`SomePackage` is downloaded from :term:`PyPI`, along with its
|
|
dependencies, and installed.
|
|
|
|
If `SomePackage` is already installed, and you need a newer version, use ``pip
|
|
install --upgrade SomePackage``. You can also request a specific version (``pip
|
|
install SomePackage==1.0.4``) and specify `setuptools extras`_ (``pip install
|
|
SomePackage[PDF]``).
|
|
|
|
You can also install from a particular source distribution file, either
|
|
local or remote::
|
|
|
|
$ pip install ./downloads/SomePackage-1.0.4.tar.gz
|
|
$ pip install http://my.package.repo/SomePackage-1.0.4.zip
|
|
|
|
.. _setuptools extras: http://peak.telecommunity.com/DevCenter/setuptools#declaring-extras-optional-features-with-their-own-dependencies
|
|
|
|
|
|
Editable mode
|
|
*************
|
|
|
|
Packages normally_ install under ``site-packages``, but when you're
|
|
making changes, it makes more sense to run the package straight from the
|
|
checked-out source tree. "Editable" installs create a ``.pth`` file in
|
|
``site-packages`` that extends Python's import path to find the
|
|
package::
|
|
|
|
$ pip install -e path/to/SomePackage
|
|
|
|
.. _normally: http://docs.python.org/install/index.html#how-installation-works
|
|
|
|
|
|
Version control systems
|
|
***********************
|
|
|
|
Pip knows how to check out a package from version control. `Subversion`,
|
|
`Git`, `Mercurial` and `Bazaar` are supported. The repository will be
|
|
checked out in a temporary folder, installed, and cleaned up::
|
|
|
|
$ pip install git+https://github.com/simplejson/simplejson.git
|
|
$ pip install svn+svn://svn.zope.org/repos/main/zope.interface/trunk/
|
|
|
|
This can be combined with the `-e` flag, and Pip will perform the
|
|
checkout in ``./src/``. You need to supply a name for the checkout
|
|
folder by appending a hash to the repository URL::
|
|
|
|
$ pip install -e git+https://github.com/lakshmivyas/hyde.git#egg=hyde
|
|
|
|
Note that only basic checking-out of a repo is supported; pip will not
|
|
handle advanced VCS-specific features such as submodules or subrepos.
|
|
|
|
|
|
Alternate package repositories
|
|
******************************
|
|
|
|
pip searches in :term:`PyPI` by default, but this can be overridden using the
|
|
``--index-url`` option::
|
|
|
|
$ pip install --index-url http://d.pypi.python.org/simple/ SomePackage
|
|
|
|
If you have your own package index with a few additional packages, you may want
|
|
to to specify additional index URLs while still also using :term:`PyPI`::
|
|
|
|
$ pip install --extra-index-url http://my.package.repo/ SomePackage
|
|
|
|
A "package index" used with ``--index-url`` or ``--extra-index-url`` can be as
|
|
simple as a static-web-served directory, with automatic indexes on, with a
|
|
subdirectory per package and sdists (tarballs created with ``python setup.py
|
|
sdist``) in that directory::
|
|
|
|
mypackage/
|
|
mypackage-0.7.8.tar.gz
|
|
mypackage-1.0.1.tar.gz
|
|
otherpackage/
|
|
otherpackage-2.3.5.tar.gz
|
|
|
|
If the number of packages in the index is small, it's even simpler to skip the
|
|
subdirectories: put all of the sdists in a single directory and use pip's
|
|
``--find-links`` option with a URL to that directory::
|
|
|
|
mypackage-0.7.8.tar.gz
|
|
mypackage-1.0.1.tar.gz
|
|
otherpackage-2.3.5.tar.gz
|
|
|
|
``--find-links`` also supports local paths, so installation need not require a
|
|
network connection.
|
|
|
|
Like ``--extra-index-url``, ``--find-links`` is additive by default, it does
|
|
not replace or supersede the index. All package sources are checked, and the
|
|
latest qualifying version for every requested package is used. If you want only
|
|
your ``-find-links`` URL used as package source, you need to pair it with
|
|
``--no-index``.
|
|
|
|
``--index-url``, ``--extra-index-url`` and ``--find-links`` can all be used
|
|
within a :ref:`requirements file <requirements-files>` in addition to on the
|
|
command line directly.
|
|
|
|
|
|
Package Checksum Hashes
|
|
'''''''''''''''''''''''
|
|
|
|
:term:`PyPI` provides a md5 hash of a package by having the link to the
|
|
package include a #md5=<hash>. pip supports this, as well as any of the
|
|
guaranteed hashlib algorithms (sha1, sha224, sha384, sha256, sha512, md5).
|
|
|
|
The hash fragment is case sensitive (i.e. sha1 not SHA1).
|
|
|
|
|
|
Uninstall packages
|
|
------------------
|
|
|
|
pip is able to uninstall most installed packages with ``pip uninstall
|
|
package-name``.
|
|
|
|
Known exceptions include pure-distutils packages installed with
|
|
``python setup.py install`` (such packages leave behind no metadata allowing
|
|
determination of what files were installed), and script wrappers installed
|
|
by develop-installs (``python setup.py develop``).
|
|
|
|
pip also performs an automatic uninstall of an old version of a package
|
|
before upgrading to a newer version, so outdated files (and egg-info data)
|
|
from conflicting versions aren't left hanging around to cause trouble. The
|
|
old version of the package is automatically restored if the new version
|
|
fails to download or install.
|
|
|
|
|
|
List installed packages
|
|
--------------------------
|
|
|
|
To list installed packages::
|
|
|
|
$ pip list
|
|
|
|
To only list editables::
|
|
|
|
$ pip list --editable
|
|
|
|
To list outdated packages (excluding editables), and the latest version available::
|
|
|
|
$ pip list --outdated
|
|
|
|
To list uptodate packages (excluding editables)::
|
|
|
|
$ pip list --uptodate
|
|
|
|
|
|
Show package status
|
|
-------------------
|
|
|
|
To get info about an installed package, including its location and included
|
|
files::
|
|
|
|
$ pip show SomePackage
|
|
|
|
|
|
Search for packages
|
|
-------------------
|
|
|
|
pip can search :term:`PyPI` for packages using the ``pip search``
|
|
command::
|
|
|
|
$ pip search "query"
|
|
|
|
The query will be used to search the names and summaries of all
|
|
packages. With the ``--index`` option you can search in a different
|
|
repository.
|
|
|
|
|
|
Bundles
|
|
-------
|
|
|
|
.. note::
|
|
|
|
Pip bundles are poorly supported, poorly tested, not widely used, and
|
|
unnecessary (the same goals can be achieved by distributing a directory of
|
|
sdists and using `--find-links` to reference it). The feature will likely be
|
|
removed in a future version of pip.
|
|
|
|
Another way to distribute a set of libraries is a bundle format (specific to
|
|
pip). This format is not stable at this time (there simply hasn't been
|
|
any feedback, nor a great deal of thought). A bundle file contains all the
|
|
source for your package, and you can have pip install them all together.
|
|
Once you have the bundle file further network access won't be necessary. To
|
|
build a bundle file, do::
|
|
|
|
$ pip bundle MyApp.pybundle MyApp
|
|
|
|
(Using a :ref:`requirements file <requirements-files>` would be wise.) Then
|
|
someone else can get the file ``MyApp.pybundle`` and run::
|
|
|
|
$ pip install MyApp.pybundle
|
|
|
|
This is *not* a binary format. This only packages source. If you have binary
|
|
packages, then the person who installs the files will have to have a compiler,
|
|
any necessary headers installed, etc. Binary packages are hard, this is
|
|
relatively easy.
|