<commit_before>=====
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.


Searching 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.


Checking installed package status
---------------------------------

To get info about an installed package, including its location and included
files, run ``pip show ProjectName``.


Wheel support
-------------

Pip has experimental support for installing "wheel" archives,
which requires distribute>=0.6.28 (not setuptools) and the latest markerlib.

To install directly from a wheel archive::

    $ pip install /path/to/SomePackage[...].whl

To have pip try to find wheels on pypi indexes or find-links::

    $ pip install --use-wheel SomePackage

Pip currently only supports finding wheels based on the python version tag, not implementation, abi or platform tags.

For more information, see the `wheel documentation <http://wheel.readthedocs.org/en/latest/index.html>`_


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::
<commit_msg>mention 'pip wheel' in docs<commit_after>=====
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.


Searching 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.


Checking installed package status
---------------------------------

To get info about an installed package, including its location and included
files, run ``pip show ProjectName``.


Wheel support
-------------

Pip has support for building and installing wheel distributions.
Wheel is a built-package format, and offers the advantage of not recompiling your software during every install.
For more details, see the `wheel docs <http://wheel.readthedocs.org/en/latest>`_.

Installing wheels requires distribute>=0.6.28 (not setuptools) and the latest `markerlib <http://pypi.python.org/pypi/markerlib>`_.
Building wheels, additionally requires `wheel <http://pypi.python.org/pypi/wheel>`_.

To build wheels for a requirement (and all it's dependencies)::

    $ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage

To install wheels from a local cache::

    $ pip install --use-wheel --no-index --find-links=/tmp/wheelhouse SomePackage


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::

{'fraction_non_alphanumeric': 0.11407854117309212, 'fraction_numerical': 0.007035680953406562, 'mean_word_length': 3.8001378359751894, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 15, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '566933', 'n_tokens_mistral': 3954, 'n_tokens_neox': 3751, 'n_words': 1761}