mirror of
https://github.com/pypa/pip
synced 2023-12-13 21:30:23 +01:00
pip docs refactor
This commit is contained in:
parent
8575e0c164
commit
9e39d9d8ca
174
CHANGES.txt
174
CHANGES.txt
|
@ -1,8 +1,7 @@
|
||||||
Changelog
|
|
||||||
=========
|
|
||||||
|
|
||||||
1.5.2 (2014-01-26)
|
|
||||||
------------------
|
**1.5.2 (2014-01-26)**
|
||||||
|
|
||||||
|
|
||||||
* Upgraded the vendored ``pkg_resources`` and ``_markerlib`` to setuptools 2.1.
|
* Upgraded the vendored ``pkg_resources`` and ``_markerlib`` to setuptools 2.1.
|
||||||
|
|
||||||
|
@ -13,8 +12,8 @@ Changelog
|
||||||
part of the URL in a requirements file
|
part of the URL in a requirements file
|
||||||
|
|
||||||
|
|
||||||
1.5.1 (2014-01-20)
|
**1.5.1 (2014-01-20)**
|
||||||
------------------
|
|
||||||
|
|
||||||
* pip now only requires setuptools (any setuptools, not a certain version) when
|
* pip now only requires setuptools (any setuptools, not a certain version) when
|
||||||
installing distributions from src (i.e. not from wheel). (Pull #1434).
|
installing distributions from src (i.e. not from wheel). (Pull #1434).
|
||||||
|
@ -32,9 +31,8 @@ Changelog
|
||||||
#1457)
|
#1457)
|
||||||
|
|
||||||
|
|
||||||
|
**1.5 (2014-01-01)**
|
||||||
|
|
||||||
1.5 (2014-01-01)
|
|
||||||
----------------
|
|
||||||
|
|
||||||
* **BACKWARD INCOMPATIBLE** pip no longer supports the ``--use-mirrors``,
|
* **BACKWARD INCOMPATIBLE** pip no longer supports the ``--use-mirrors``,
|
||||||
``-M``, and ``--mirrors`` flags. The mirroring support has been removed. In
|
``-M``, and ``--mirrors`` flags. The mirroring support has been removed. In
|
||||||
|
@ -110,11 +108,9 @@ Changelog
|
||||||
(Pull #1316)
|
(Pull #1316)
|
||||||
|
|
||||||
|
|
||||||
|
**1.4.1 (2013-08-07)**
|
||||||
|
|
||||||
|
|
||||||
1.4.1 (2013-08-07)
|
|
||||||
------------------
|
|
||||||
|
|
||||||
* **New Signing Key** Release 1.4.1 is using a different key than normal with
|
* **New Signing Key** Release 1.4.1 is using a different key than normal with
|
||||||
fingerprint: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
|
fingerprint: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
|
||||||
* Fixed issues with installing from pybundle files (Pull #1116).
|
* Fixed issues with installing from pybundle files (Pull #1116).
|
||||||
|
@ -125,8 +121,8 @@ Changelog
|
||||||
* Fixes related to recognizing and cleaning global build dirs (Pull #1080).
|
* Fixes related to recognizing and cleaning global build dirs (Pull #1080).
|
||||||
|
|
||||||
|
|
||||||
1.4 (2013-07-23)
|
**1.4 (2013-07-23)**
|
||||||
----------------
|
|
||||||
|
|
||||||
* **BACKWARD INCOMPATIBLE** pip now only installs stable versions by default,
|
* **BACKWARD INCOMPATIBLE** pip now only installs stable versions by default,
|
||||||
and offers a new ``--pre`` option to also find pre-release and development
|
and offers a new ``--pre`` option to also find pre-release and development
|
||||||
|
@ -174,14 +170,16 @@ Changelog
|
||||||
|
|
||||||
* Fixed git VCS backend with git 1.8.3. (Pull #967)
|
* Fixed git VCS backend with git 1.8.3. (Pull #967)
|
||||||
|
|
||||||
1.3.1 (2013-03-08)
|
|
||||||
------------------
|
**1.3.1 (2013-03-08)**
|
||||||
|
|
||||||
|
|
||||||
* Fixed a major backward incompatible change of parsing URLs to externally
|
* Fixed a major backward incompatible change of parsing URLs to externally
|
||||||
hosted packages that got accidentily included in 1.3.
|
hosted packages that got accidentily included in 1.3.
|
||||||
|
|
||||||
1.3 (2013-03-07)
|
|
||||||
----------------
|
**1.3 (2013-03-07)**
|
||||||
|
|
||||||
|
|
||||||
* SSL Cert Verification; Make https the default for PyPI access.
|
* SSL Cert Verification; Make https the default for PyPI access.
|
||||||
Thanks James Cleveland, Giovanni Bajo, Marcus Smith and many others (Pull #791, CVE-2013-1629).
|
Thanks James Cleveland, Giovanni Bajo, Marcus Smith and many others (Pull #791, CVE-2013-1629).
|
||||||
|
@ -237,15 +235,17 @@ Changelog
|
||||||
like the same option in distutils but also plays nice with pip's egg-info.
|
like the same option in distutils but also plays nice with pip's egg-info.
|
||||||
Thanks Przemek Wrzos. (Issue #253 / Pull #693)
|
Thanks Przemek Wrzos. (Issue #253 / Pull #693)
|
||||||
|
|
||||||
1.2.1 (2012-09-06)
|
|
||||||
------------------
|
**1.2.1 (2012-09-06)**
|
||||||
|
|
||||||
|
|
||||||
* Fixed a regression introduced in 1.2 about raising an exception when
|
* Fixed a regression introduced in 1.2 about raising an exception when
|
||||||
not finding any files to uninstall in the current environment. Thanks for
|
not finding any files to uninstall in the current environment. Thanks for
|
||||||
the fix, Marcus Smith.
|
the fix, Marcus Smith.
|
||||||
|
|
||||||
1.2 (2012-09-01)
|
|
||||||
----------------
|
**1.2 (2012-09-01)**
|
||||||
|
|
||||||
|
|
||||||
* **Dropped support for Python 2.4** The minimum supported Python version is
|
* **Dropped support for Python 2.4** The minimum supported Python version is
|
||||||
now Python 2.5.
|
now Python 2.5.
|
||||||
|
@ -313,8 +313,9 @@ Changelog
|
||||||
|
|
||||||
* Added a better help formatter.
|
* Added a better help formatter.
|
||||||
|
|
||||||
1.1 (2012-02-16)
|
|
||||||
----------------
|
**1.1 (2012-02-16)**
|
||||||
|
|
||||||
|
|
||||||
* Fixed issue #326 - don't crash when a package's setup.py emits UTF-8 and
|
* Fixed issue #326 - don't crash when a package's setup.py emits UTF-8 and
|
||||||
then fails. Thanks Marc Abramowitz.
|
then fails. Thanks Marc Abramowitz.
|
||||||
|
@ -373,8 +374,8 @@ Changelog
|
||||||
requirements from VCS that have a changed repo URL.
|
requirements from VCS that have a changed repo URL.
|
||||||
|
|
||||||
|
|
||||||
1.0.2 (2011-07-16)
|
**1.0.2 (2011-07-16)**
|
||||||
------------------
|
|
||||||
|
|
||||||
* Fixed docs issues.
|
* Fixed docs issues.
|
||||||
* Fixed issue #295 - Reinstall a package when using the ``install -I`` option
|
* Fixed issue #295 - Reinstall a package when using the ``install -I`` option
|
||||||
|
@ -383,8 +384,9 @@ Changelog
|
||||||
* Fixed issue #314 - Correctly handle exceptions on Python3.
|
* Fixed issue #314 - Correctly handle exceptions on Python3.
|
||||||
* Fixed issue #320 - Correctly parse ``--editable`` lines in requirements files
|
* Fixed issue #320 - Correctly parse ``--editable`` lines in requirements files
|
||||||
|
|
||||||
1.0.1 (2011-04-30)
|
|
||||||
------------------
|
**1.0.1 (2011-04-30)**
|
||||||
|
|
||||||
|
|
||||||
* Start to use git-flow.
|
* Start to use git-flow.
|
||||||
* Fixed issue #274 - `find_command` should not raise AttributeError
|
* Fixed issue #274 - `find_command` should not raise AttributeError
|
||||||
|
@ -394,8 +396,9 @@ Changelog
|
||||||
* Fixed issue #44 - multiple CLI searches.
|
* Fixed issue #44 - multiple CLI searches.
|
||||||
* Fixed issue #266 - current working directory when running setup.py clean.
|
* Fixed issue #266 - current working directory when running setup.py clean.
|
||||||
|
|
||||||
1.0 (2011-04-04)
|
|
||||||
----------------
|
**1.0 (2011-04-04)**
|
||||||
|
|
||||||
|
|
||||||
* Added Python 3 support! Huge thanks to Vinay Sajip, Vitaly Babiy, Kelsey
|
* Added Python 3 support! Huge thanks to Vinay Sajip, Vitaly Babiy, Kelsey
|
||||||
Hightower, and Alex Gronholm, among others.
|
Hightower, and Alex Gronholm, among others.
|
||||||
|
@ -422,8 +425,9 @@ Changelog
|
||||||
Make sure you have `distribute <http://pypi.python.org/pypi/distribute>`_
|
Make sure you have `distribute <http://pypi.python.org/pypi/distribute>`_
|
||||||
installed before using the installer!
|
installed before using the installer!
|
||||||
|
|
||||||
0.8.3
|
|
||||||
-----
|
**0.8.3**
|
||||||
|
|
||||||
|
|
||||||
* Moved main repository to Github: https://github.com/pypa/pip
|
* Moved main repository to Github: https://github.com/pypa/pip
|
||||||
|
|
||||||
|
@ -445,8 +449,9 @@ Changelog
|
||||||
|
|
||||||
* Fixed bug in version string parsing related to the suffix "-dev".
|
* Fixed bug in version string parsing related to the suffix "-dev".
|
||||||
|
|
||||||
0.8.2
|
|
||||||
-----
|
**0.8.2**
|
||||||
|
|
||||||
|
|
||||||
* Avoid redundant unpacking of bundles (from pwaller)
|
* Avoid redundant unpacking of bundles (from pwaller)
|
||||||
|
|
||||||
|
@ -462,8 +467,9 @@ Changelog
|
||||||
|
|
||||||
* Added ``git+https://`` scheme to Git VCS backend.
|
* Added ``git+https://`` scheme to Git VCS backend.
|
||||||
|
|
||||||
0.8.1
|
|
||||||
-----
|
**0.8.1**
|
||||||
|
|
||||||
|
|
||||||
* Added global --user flag as shortcut for --install-option="--user". From
|
* Added global --user flag as shortcut for --install-option="--user". From
|
||||||
Ronny Pfannschmidt.
|
Ronny Pfannschmidt.
|
||||||
|
@ -482,9 +488,8 @@ Changelog
|
||||||
Thanks Ronny Pfannschmidt and Wil Tan.
|
Thanks Ronny Pfannschmidt and Wil Tan.
|
||||||
|
|
||||||
|
|
||||||
|
**0.8**
|
||||||
|
|
||||||
0.8
|
|
||||||
---
|
|
||||||
|
|
||||||
* Track which ``build/`` directories pip creates, never remove directories
|
* Track which ``build/`` directories pip creates, never remove directories
|
||||||
it doesn't create. From Hugo Lopes Tavares.
|
it doesn't create. From Hugo Lopes Tavares.
|
||||||
|
@ -510,14 +515,16 @@ Changelog
|
||||||
|
|
||||||
* Significant test framework changes, from Hugo Lopes Tavares.
|
* Significant test framework changes, from Hugo Lopes Tavares.
|
||||||
|
|
||||||
0.7.2
|
|
||||||
-----
|
**0.7.2**
|
||||||
|
|
||||||
|
|
||||||
* Set zip_safe=False to avoid problems some people are encountering where
|
* Set zip_safe=False to avoid problems some people are encountering where
|
||||||
pip is installed as a zip file.
|
pip is installed as a zip file.
|
||||||
|
|
||||||
0.7.1
|
|
||||||
-----
|
**0.7.1**
|
||||||
|
|
||||||
|
|
||||||
* Fixed opening of logfile with no directory name. Thanks Alexandre Conrad.
|
* Fixed opening of logfile with no directory name. Thanks Alexandre Conrad.
|
||||||
|
|
||||||
|
@ -526,8 +533,9 @@ Changelog
|
||||||
|
|
||||||
* Tests now require at least ScriptTest 1.0.3.
|
* Tests now require at least ScriptTest 1.0.3.
|
||||||
|
|
||||||
0.7
|
|
||||||
---
|
**0.7**
|
||||||
|
|
||||||
|
|
||||||
* Fixed uninstallation on Windows
|
* Fixed uninstallation on Windows
|
||||||
* Added ``pip search`` command.
|
* Added ``pip search`` command.
|
||||||
|
@ -568,21 +576,24 @@ Changelog
|
||||||
--extra-index-url.
|
--extra-index-url.
|
||||||
* Leftover build directories are now removed. Thanks Alexandre Conrad.
|
* Leftover build directories are now removed. Thanks Alexandre Conrad.
|
||||||
|
|
||||||
0.6.3
|
|
||||||
-----
|
**0.6.3**
|
||||||
|
|
||||||
|
|
||||||
* Fixed import error on Windows with regard to the backwards compatibility
|
* Fixed import error on Windows with regard to the backwards compatibility
|
||||||
package
|
package
|
||||||
|
|
||||||
0.6.2
|
|
||||||
-----
|
**0.6.2**
|
||||||
|
|
||||||
|
|
||||||
* Fixed uninstall when /tmp is on a different filesystem.
|
* Fixed uninstall when /tmp is on a different filesystem.
|
||||||
|
|
||||||
* Fixed uninstallation of distributions with namespace packages.
|
* Fixed uninstallation of distributions with namespace packages.
|
||||||
|
|
||||||
0.6.1
|
|
||||||
-----
|
**0.6.1**
|
||||||
|
|
||||||
|
|
||||||
* Added support for the ``https`` and ``http-static`` schemes to the
|
* Added support for the ``https`` and ``http-static`` schemes to the
|
||||||
Mercurial and ``ftp`` scheme to the Bazaar backend.
|
Mercurial and ``ftp`` scheme to the Bazaar backend.
|
||||||
|
@ -595,8 +606,9 @@ Changelog
|
||||||
* Fixed issue with ``pip bundle`` and local files (which weren't being
|
* Fixed issue with ``pip bundle`` and local files (which weren't being
|
||||||
copied into the bundle), from Whit Morriss.
|
copied into the bundle), from Whit Morriss.
|
||||||
|
|
||||||
0.6
|
|
||||||
---
|
**0.6**
|
||||||
|
|
||||||
|
|
||||||
* Add ``pip uninstall`` and uninstall-before upgrade (from Carl
|
* Add ``pip uninstall`` and uninstall-before upgrade (from Carl
|
||||||
Meyer).
|
Meyer).
|
||||||
|
@ -626,13 +638,15 @@ Changelog
|
||||||
|
|
||||||
* Creates download cache directory if not existing.
|
* Creates download cache directory if not existing.
|
||||||
|
|
||||||
0.5.1
|
|
||||||
-----
|
**0.5.1**
|
||||||
|
|
||||||
|
|
||||||
* Fixed a couple little bugs, with git and with extensions.
|
* Fixed a couple little bugs, with git and with extensions.
|
||||||
|
|
||||||
0.5
|
|
||||||
---
|
**0.5**
|
||||||
|
|
||||||
|
|
||||||
* Added ability to override the default log file name (``pip-log.txt``)
|
* Added ability to override the default log file name (``pip-log.txt``)
|
||||||
with the environmental variable ``$PIP_LOG_FILE``.
|
with the environmental variable ``$PIP_LOG_FILE``.
|
||||||
|
@ -684,8 +698,9 @@ Changelog
|
||||||
* Fixed handling of attempt to checkout editable install to a
|
* Fixed handling of attempt to checkout editable install to a
|
||||||
non-empty, non-repo directory.
|
non-empty, non-repo directory.
|
||||||
|
|
||||||
0.4
|
|
||||||
---
|
**0.4**
|
||||||
|
|
||||||
|
|
||||||
* Make ``-e`` work better with local hg repositories
|
* Make ``-e`` work better with local hg repositories
|
||||||
|
|
||||||
|
@ -713,8 +728,9 @@ Changelog
|
||||||
|
|
||||||
* Fixed support for Subversion 1.6.
|
* Fixed support for Subversion 1.6.
|
||||||
|
|
||||||
0.3.1
|
|
||||||
-----
|
**0.3.1**
|
||||||
|
|
||||||
|
|
||||||
* Improved virtualenv restart and various path/cleanup problems on win32.
|
* Improved virtualenv restart and various path/cleanup problems on win32.
|
||||||
|
|
||||||
|
@ -726,8 +742,9 @@ Changelog
|
||||||
|
|
||||||
* Improve ``pip -h``
|
* Improve ``pip -h``
|
||||||
|
|
||||||
0.3
|
|
||||||
---
|
**0.3**
|
||||||
|
|
||||||
|
|
||||||
* Added support for editable packages created from Git, Mercurial and Bazaar
|
* Added support for editable packages created from Git, Mercurial and Bazaar
|
||||||
repositories and ability to freeze them. Refactored support for version
|
repositories and ability to freeze them. Refactored support for version
|
||||||
|
@ -763,8 +780,9 @@ Changelog
|
||||||
|
|
||||||
* Add ``--simulate`` option to ``pip zip``.
|
* Add ``--simulate`` option to ``pip zip``.
|
||||||
|
|
||||||
0.2.1
|
|
||||||
-----
|
**0.2.1**
|
||||||
|
|
||||||
|
|
||||||
* Fixed small problem that prevented using ``pip.py`` without actually
|
* Fixed small problem that prevented using ``pip.py`` without actually
|
||||||
installing pip.
|
installing pip.
|
||||||
|
@ -783,8 +801,9 @@ Changelog
|
||||||
|
|
||||||
* Turn some tar file errors into warnings.
|
* Turn some tar file errors into warnings.
|
||||||
|
|
||||||
0.2
|
|
||||||
---
|
**0.2**
|
||||||
|
|
||||||
|
|
||||||
* Renamed to ``pip``, and to install you now do ``pip install
|
* Renamed to ``pip``, and to install you now do ``pip install
|
||||||
PACKAGE``
|
PACKAGE``
|
||||||
|
@ -797,8 +816,9 @@ Changelog
|
||||||
creating a bundle using unnamed packages (like just an svn
|
creating a bundle using unnamed packages (like just an svn
|
||||||
repository without ``#egg=Package``).
|
repository without ``#egg=Package``).
|
||||||
|
|
||||||
0.1.4
|
|
||||||
-----
|
**0.1.4**
|
||||||
|
|
||||||
|
|
||||||
* Added an option ``--install-option`` to pass options to pass
|
* Added an option ``--install-option`` to pass options to pass
|
||||||
arguments to ``setup.py install``
|
arguments to ``setup.py install``
|
||||||
|
@ -824,16 +844,18 @@ Changelog
|
||||||
is still required, but just some downloads will be avoided when
|
is still required, but just some downloads will be avoided when
|
||||||
using this.
|
using this.
|
||||||
|
|
||||||
0.1.3
|
|
||||||
-----
|
**0.1.3**
|
||||||
|
|
||||||
|
|
||||||
* Always use ``svn checkout`` (not ``export``) so that
|
* Always use ``svn checkout`` (not ``export``) so that
|
||||||
``tag_svn_revision`` settings give the revision of the package.
|
``tag_svn_revision`` settings give the revision of the package.
|
||||||
|
|
||||||
* Don't update checkouts that came from ``.pybundle`` files.
|
* Don't update checkouts that came from ``.pybundle`` files.
|
||||||
|
|
||||||
0.1.2
|
|
||||||
-----
|
**0.1.2**
|
||||||
|
|
||||||
|
|
||||||
* Improve error text when there are errors fetching HTML pages when
|
* Improve error text when there are errors fetching HTML pages when
|
||||||
seeking packages.
|
seeking packages.
|
||||||
|
@ -846,8 +868,9 @@ Changelog
|
||||||
|
|
||||||
* Fix ``dependency_links`` for finding packages.
|
* Fix ``dependency_links`` for finding packages.
|
||||||
|
|
||||||
0.1.1
|
|
||||||
-----
|
**0.1.1**
|
||||||
|
|
||||||
|
|
||||||
* Fixed a NameError exception when running pip outside of a
|
* Fixed a NameError exception when running pip outside of a
|
||||||
virtualenv environment.
|
virtualenv environment.
|
||||||
|
@ -857,7 +880,8 @@ Changelog
|
||||||
* Fixed use of ``hashlib.md5`` on python2.5+ (also from Prabhu
|
* Fixed use of ``hashlib.md5`` on python2.5+ (also from Prabhu
|
||||||
Ramachandran)
|
Ramachandran)
|
||||||
|
|
||||||
0.1
|
|
||||||
---
|
**0.1**
|
||||||
|
|
||||||
|
|
||||||
* Initial release
|
* Initial release
|
||||||
|
|
|
@ -7,4 +7,5 @@ Project Info
|
||||||
* Bug Tracking: https://github.com/pypa/pip/issues
|
* Bug Tracking: https://github.com/pypa/pip/issues
|
||||||
* Mailing list: http://groups.google.com/group/python-virtualenv
|
* Mailing list: http://groups.google.com/group/python-virtualenv
|
||||||
* Docs: http://www.pip-installer.org/
|
* Docs: http://www.pip-installer.org/
|
||||||
* IRC: #pip on Freenode.
|
* User IRC: #pip on Freenode.
|
||||||
|
* Dev IRC: #pypa on Freenode.
|
||||||
|
|
|
@ -1,126 +1,8 @@
|
||||||
.. _`Configuration`:
|
:orphan:
|
||||||
|
|
||||||
Configuration
|
Configuration
|
||||||
=================
|
=============
|
||||||
|
|
||||||
.. _config-file:
|
This content is now covered in the :doc:`User Guide <user_guide>`
|
||||||
|
|
||||||
Config file
|
|
||||||
------------
|
|
||||||
|
|
||||||
pip allows you to set all command line option defaults in a standard ini
|
|
||||||
style config file.
|
|
||||||
|
|
||||||
The names and locations of the configuration files vary slightly across
|
|
||||||
platforms.
|
|
||||||
|
|
||||||
* On Unix and Mac OS X the configuration file is: :file:`$HOME/.pip/pip.conf`
|
|
||||||
* On Windows, the configuration file is: :file:`%HOME%\\pip\\pip.ini`
|
|
||||||
|
|
||||||
You can set a custom path location for the config file using the environment variable ``PIP_CONFIG_FILE``.
|
|
||||||
|
|
||||||
The names of the settings are derived from the long command line option, e.g.
|
|
||||||
if you want to use a different package index (``--index-url``) and set the
|
|
||||||
HTTP timeout (``--default-timeout``) to 60 seconds your config file would
|
|
||||||
look like this:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
[global]
|
|
||||||
timeout = 60
|
|
||||||
index-url = http://download.zope.org/ppix
|
|
||||||
|
|
||||||
Each subcommand can be configured optionally in its own section so that every
|
|
||||||
global setting with the same name will be overridden; e.g. decreasing the
|
|
||||||
``timeout`` to ``10`` seconds when running the `freeze`
|
|
||||||
(`Freezing Requirements <./#freezing-requirements>`_) command and using
|
|
||||||
``60`` seconds for all other commands is possible with:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
[global]
|
|
||||||
timeout = 60
|
|
||||||
|
|
||||||
[freeze]
|
|
||||||
timeout = 10
|
|
||||||
|
|
||||||
|
|
||||||
Boolean options like ``--ignore-installed`` or ``--no-dependencies`` can be
|
|
||||||
set like this:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
[install]
|
|
||||||
ignore-installed = true
|
|
||||||
no-dependencies = yes
|
|
||||||
|
|
||||||
Appending options like ``--find-links`` can be written on multiple lines:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
[global]
|
|
||||||
find-links =
|
|
||||||
http://download.example.com
|
|
||||||
|
|
||||||
[install]
|
|
||||||
find-links =
|
|
||||||
http://mirror1.example.com
|
|
||||||
http://mirror2.example.com
|
|
||||||
|
|
||||||
|
|
||||||
Environment Variables
|
|
||||||
---------------------
|
|
||||||
|
|
||||||
pip's command line options can be set with
|
|
||||||
environment variables using the format ``PIP_<UPPER_LONG_NAME>`` . Dashes (``-``) have to replaced with underscores (``_``).
|
|
||||||
|
|
||||||
For example, to set the default timeout::
|
|
||||||
|
|
||||||
export PIP_DEFAULT_TIMEOUT=60
|
|
||||||
|
|
||||||
This is the same as passing the option to pip directly::
|
|
||||||
|
|
||||||
pip --default-timeout=60 [...]
|
|
||||||
|
|
||||||
To set options that can be set multiple times on the command line, just add spaces in between values. For example::
|
|
||||||
|
|
||||||
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
|
|
||||||
|
|
||||||
is the same as calling::
|
|
||||||
|
|
||||||
pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
|
|
||||||
|
|
||||||
|
|
||||||
Config Precedence
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
Command line options have precedence over environment variables, which have precedence over the config file.
|
|
||||||
|
|
||||||
Within the config file, command specific sections have precedence over the global section.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
- ``--host=foo`` overrides ``PIP_HOST=foo``
|
|
||||||
- ``PIP_HOST=foo`` overrides a config file with ``[global] host = foo``
|
|
||||||
- A command specific section in the config file ``[<command>] host = bar``
|
|
||||||
overrides the option with same name in the ``[global]`` config file section
|
|
||||||
|
|
||||||
|
|
||||||
Command Completion
|
|
||||||
------------------
|
|
||||||
|
|
||||||
pip comes with support for command line completion in bash and zsh.
|
|
||||||
|
|
||||||
To setup for bash::
|
|
||||||
|
|
||||||
$ pip completion --bash >> ~/.profile
|
|
||||||
|
|
||||||
To setup for zsh::
|
|
||||||
|
|
||||||
$ pip completion --zsh >> ~/.zprofile
|
|
||||||
|
|
||||||
Alternatively, you can use the result of the ``completion`` command
|
|
||||||
directly with the eval function of you shell, e.g. by adding the following to your startup file::
|
|
||||||
|
|
||||||
eval "`pip completion --bash`"
|
|
||||||
|
|
||||||
|
|
|
@ -1,453 +1,8 @@
|
||||||
|
:orphan:
|
||||||
|
|
||||||
============
|
============
|
||||||
Cookbook
|
Cookbook
|
||||||
============
|
============
|
||||||
|
|
||||||
.. _`Requirements Files`:
|
This content is now covered in the :doc:`User Guide <user_guide>`
|
||||||
|
|
||||||
Requirements Files
|
|
||||||
******************
|
|
||||||
|
|
||||||
"Requirements files" are files containing a list of items to be
|
|
||||||
installed using :ref:`pip install -r <install_--requirement>` like so:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
|
|
||||||
Details on the format of the files are here: :ref:`Requirements File Format`.
|
|
||||||
|
|
||||||
|
|
||||||
There are 3 common use cases for requirements files:
|
|
||||||
|
|
||||||
1. When installing many things, it's easier to use a requirements file,
|
|
||||||
than specifying them all on the command line.
|
|
||||||
|
|
||||||
2. Requirements files are often used to hold the result from :ref:`pip freeze`
|
|
||||||
for the purpose of achieving :ref:`repeatable installations <Repeatability>`.
|
|
||||||
In this case, your requirement file contains a pinned version of everything
|
|
||||||
that was installed when `pip freeze` was run.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pip freeze > requirements.txt
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
3. Requirements files can be used to force pip to properly resolve dependencies.
|
|
||||||
As it is now, pip `doesn't have true dependency resolution
|
|
||||||
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses the first
|
|
||||||
specification it finds for a project. E.g if `pkg1` requires `pkg3>=1.0` and
|
|
||||||
`pkg2` requires `pkg3>=1.0,<=2.0`, and if `pkg1` is resolved first, pip will
|
|
||||||
only use `pkg3>=1.0`, and could easily end up installing a version of `pkg3`
|
|
||||||
that conflicts with the needs of `pkg2`. To solve this problem, you can
|
|
||||||
place `pkg3>=1.0,<=2.0` (i.e. the correct specification) into your
|
|
||||||
requirements file directly along with the other top level requirements. Like
|
|
||||||
so:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pkg1
|
|
||||||
pkg2
|
|
||||||
pkg3>=1.0,<=2.0
|
|
||||||
|
|
||||||
|
|
||||||
It's important to be clear that pip determines package dependencies using `install_requires metadata
|
|
||||||
<http://pythonhosted.org/setuptools/setuptools.html#declaring-dependencies>`_, not by discovering `requirements.txt`
|
|
||||||
files embedded in projects.
|
|
||||||
|
|
||||||
For a good discussion on the conceptual differences between setup.py and
|
|
||||||
requirements, see `"setup.py vs requirements.txt" (an article by Donald Stufft)
|
|
||||||
<https://caremad.io/blog/setup-vs-requirement/>`_
|
|
||||||
|
|
||||||
See also:
|
|
||||||
|
|
||||||
* :ref:`Requirements File Format`
|
|
||||||
* :ref:`pip freeze`
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Fast & Local Installs`:
|
|
||||||
|
|
||||||
Fast & Local Installs
|
|
||||||
*********************
|
|
||||||
|
|
||||||
Often, you will want a fast install from local archives, without probing PyPI.
|
|
||||||
|
|
||||||
First, :ref:`download the archives <Downloading Archives>` that fulfill your requirements::
|
|
||||||
|
|
||||||
$ pip install --download <DIR> -r requirements.txt
|
|
||||||
|
|
||||||
Then, install using :ref:`--find-links <--find-links>` and :ref:`--no-index <--no-index>`::
|
|
||||||
|
|
||||||
$ pip install --no-index --find-links=[file://]<DIR> -r requirements.txt
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Building and Installing Wheels`:
|
|
||||||
|
|
||||||
Building and Installing Wheels
|
|
||||||
******************************
|
|
||||||
|
|
||||||
"Wheel" is a built, archive format that can greatly speed installation compared
|
|
||||||
to building and installing from source archives. For more information, see the
|
|
||||||
`Wheel docs <http://wheel.readthedocs.org>`_ ,
|
|
||||||
`PEP427 <http://www.python.org/dev/peps/pep-0427>`_, and
|
|
||||||
`PEP425 <http://www.python.org/dev/peps/pep-0425>`_
|
|
||||||
|
|
||||||
Pip prefers Wheels where they are available, to disable this use the
|
|
||||||
:ref:`--no-use-wheel <install_--no-use-wheel>` flag for :ref:`pip install`.
|
|
||||||
|
|
||||||
If no satisfactory wheels are found, pip will default to finding source archives.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
pip currently disallows platform-specific wheels (except for Windows and Mac)
|
|
||||||
from being downloaded from PyPI. See :ref:`Should you upload wheels to PyPI`.
|
|
||||||
|
|
||||||
|
|
||||||
To install directly from a wheel archive:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pip install SomePackage-1.0-py2.py3-none-any.whl
|
|
||||||
|
|
||||||
|
|
||||||
pip additionally offers :ref:`pip wheel` as a convenience, to build wheels for
|
|
||||||
your requirements and dependencies.
|
|
||||||
|
|
||||||
:ref:`pip wheel` requires the `wheel package <https://pypi.python.org/pypi/wheel>`_ to be installed,
|
|
||||||
which provides the "bdist_wheel" setuptools extension that it uses.
|
|
||||||
|
|
||||||
To build wheels for your requirements and all their dependencies to a local directory:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pip install wheel
|
|
||||||
pip wheel --wheel-dir=/local/wheels -r requirements.txt
|
|
||||||
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
Currently, when ``pip wheel`` finds a wheel for one of your requirements
|
|
||||||
already on PyPI, it does not rebuild, and it does not place the file in your
|
|
||||||
wheelhouse dir. There is an issue open to change this
|
|
||||||
(https://github.com/pypa/pip/issues/1310)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
And *then* to install those requirements just using your local directory of wheels (and not from PyPI):
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pip install --no-index --find-links=/local/wheels -r requirements.txt
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Should you upload wheels to PyPI`:
|
|
||||||
|
|
||||||
Should you upload wheels to PyPI?
|
|
||||||
---------------------------------
|
|
||||||
|
|
||||||
The wheel format can eliminate a lot of redundant compilation but, alas,
|
|
||||||
it's not generally advisable to upload your pre-compiled linux-x86-64
|
|
||||||
library binding to pypi. Wheel's tags are only designed to express
|
|
||||||
the most important *Python*-specific compatibility concerns (Python
|
|
||||||
version, ABI, and architecture) but do not represent other important
|
|
||||||
binary compatibility factors such as the OS release, patch level, and
|
|
||||||
the versions of all the shared library dependencies of any extensions
|
|
||||||
inside the package.
|
|
||||||
|
|
||||||
Rather than representing all possible compatibility information in the
|
|
||||||
wheel itself, the wheel design suggests distribution-specific build
|
|
||||||
services (e.g. a separate index for Fedora Linux binary wheels, compiled
|
|
||||||
by the index maintainer). This is the same solution taken by Linux
|
|
||||||
distributions which all re-compile their own packages instead of installing
|
|
||||||
each other's binary packages.
|
|
||||||
|
|
||||||
Some kinds of precompiled C extension modules can make sense on PyPI, even
|
|
||||||
for Linux. Good examples include things that can be sensibly statically
|
|
||||||
linked (a cryptographic hash function; an accelerator module that is
|
|
||||||
not a binding for an external library); the best example of something
|
|
||||||
that shouldn't be statically linked is a library like openssl that needs
|
|
||||||
to be constantly kept up-to-date for security. Regardless of whether a
|
|
||||||
compatible pre-build package is available, many Linux users will prefer
|
|
||||||
to always compile their own anyway.
|
|
||||||
|
|
||||||
On Windows and Mac, the case for binary wheels on pypi is stronger due to the
|
|
||||||
systems being much more uniform than Linux and because it's harder for the end
|
|
||||||
user to compile their own. Windows and Mac wheels uploaded to pypi should be
|
|
||||||
compatible with the Python distributions downloaded from http://python.org/. If
|
|
||||||
you already upload other binary formats to pypi, upload wheels as well. Unlike
|
|
||||||
the older formats, wheels are compatible with virtual environments.
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Downloading Archives`:
|
|
||||||
|
|
||||||
Downloading archives
|
|
||||||
********************
|
|
||||||
|
|
||||||
pip allows you to *just* download the source archives for your requirements, without installing anything and without regard to what's already installed.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install --download <DIR> -r requirements.txt
|
|
||||||
|
|
||||||
or, for a specific package::
|
|
||||||
|
|
||||||
$ pip install --download <DIR> SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
Unpacking archives
|
|
||||||
******************
|
|
||||||
|
|
||||||
pip allows you to *just* unpack archives to a build directory without installing them to site-packages. This can be useful to troubleshoot install errors or to inspect what is being installed.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install --no-install SomePackage
|
|
||||||
|
|
||||||
If you're in a virtualenv, the build dir is ``<virtualenv path>/build``. Otherwise, it's ``<OS temp dir>/pip-build-<username>``
|
|
||||||
|
|
||||||
Afterwards, to finish the job of installing unpacked archives, run::
|
|
||||||
|
|
||||||
$ pip install --no-download SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Non-recursive upgrades
|
|
||||||
************************
|
|
||||||
|
|
||||||
``pip install --upgrade`` is currently written to perform a recursive upgrade.
|
|
||||||
|
|
||||||
E.g. supposing:
|
|
||||||
|
|
||||||
* `SomePackage-1.0` requires `AnotherPackage>=1.0`
|
|
||||||
* `SomePackage-2.0` requires `AnotherPackage>=1.0` and `OneMorePoject==1.0`
|
|
||||||
* `SomePackage-1.0` and `AnotherPackage-1.0` are currently installed
|
|
||||||
* `SomePackage-2.0` and `AnotherPackage-2.0` are the latest versions available on PyPI.
|
|
||||||
|
|
||||||
Running ``pip install --upgrade SomePackage`` would upgrade `SomePackage` *and* `AnotherPackage`
|
|
||||||
despite `AnotherPackage` already being satisifed.
|
|
||||||
|
|
||||||
If you would like to perform a non-recursive upgrade perform these 2 steps::
|
|
||||||
|
|
||||||
pip install --upgrade --no-deps SomePackage
|
|
||||||
pip install SomePackage
|
|
||||||
|
|
||||||
The first line will upgrade `SomePackage`, but not dependencies like `AnotherPackage`. The 2nd line will fill in new dependencies like `OneMorePackage`.
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Repeatability`:
|
|
||||||
|
|
||||||
Ensuring Repeatability
|
|
||||||
**********************
|
|
||||||
|
|
||||||
Three things are required to fully guarantee a repeatable installation using requirements files.
|
|
||||||
|
|
||||||
1. The requirements file was generated by ``pip freeze`` or you're sure it only
|
|
||||||
contains requirements that specify a specific version.
|
|
||||||
2. The installation is performed using :ref:`--no-deps <install_--no-deps>`.
|
|
||||||
This guarantees that only what is explicitly listed in the requirements file is
|
|
||||||
installed.
|
|
||||||
3. The installation is performed against an index or find-links location that is
|
|
||||||
guaranteed to *not* allow archives to be changed and updated without a
|
|
||||||
version increase. Unfortunately, this is *not* true on PyPI. It is possible
|
|
||||||
for the same pypi distribution to have a different hash over time. Project
|
|
||||||
authors are allowed to delete a distribution, and then upload a new one with
|
|
||||||
the same name and version, but a different hash. See `Issue #1175
|
|
||||||
<https://github.com/pypa/pip/issues/1175>`_ for plans to add hash
|
|
||||||
confirmation to pip, or a new "lock file" notion, but for now, know that the `peep
|
|
||||||
project <https://pypi.python.org/pypi/peep>`_ offers this feature on top of pip
|
|
||||||
using requirements file comments.
|
|
||||||
|
|
||||||
User Installs
|
|
||||||
*************
|
|
||||||
|
|
||||||
With Python 2.6 came the `"user scheme" for installation
|
|
||||||
<http://docs.python.org/install/index.html#alternate-installation-the-user-scheme>`_, which means that all
|
|
||||||
Python distributions support an alternative install location that is specific to a user.
|
|
||||||
The default location for each OS is explained in the python documentation
|
|
||||||
for the `site.USER_BASE <http://docs.python.org/library/site.html#site.USER_BASE>`_ variable.
|
|
||||||
This mode of installation can be turned on by
|
|
||||||
specifying the :ref:`--user <install_--user>` option to ``pip install``.
|
|
||||||
|
|
||||||
Moreover, the "user scheme" can be customized by setting the
|
|
||||||
``PYTHONUSERBASE`` environment variable, which updates the value of ``site.USER_BASE``.
|
|
||||||
|
|
||||||
To install "SomePackage" into an environment with site.USER_BASE customized to '/myappenv', do the following::
|
|
||||||
|
|
||||||
export PYTHONUSERBASE=/myappenv
|
|
||||||
pip install --user SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
``pip install --user`` follows four rules:
|
|
||||||
|
|
||||||
#. When globally installed packages are on the python path, and they *conflict*
|
|
||||||
with the installation requirements, they are ignored, and *not*
|
|
||||||
uninstalled.
|
|
||||||
#. When globally installed packages are on the python path, and they *satisfy*
|
|
||||||
the installation requirements, pip does nothing, and reports that
|
|
||||||
requirement is satisfied (similar to how global packages can satisfy
|
|
||||||
requirements when installing packages in a ``--system-site-packages``
|
|
||||||
virtualenv).
|
|
||||||
#. pip will not perform a ``--user`` install in a ``--no-site-packages``
|
|
||||||
virtualenv (i.e. the default kind of virtualenv), due to the user site not
|
|
||||||
being on the python path. The installation would be pointless.
|
|
||||||
#. In a ``--system-site-packages`` virtualenv, pip will not install a package
|
|
||||||
that conflicts with a package in the virtualenv site-packages. The --user
|
|
||||||
installation would lack sys.path precedence and be pointless.
|
|
||||||
|
|
||||||
|
|
||||||
To make the rules clearer, here are some examples:
|
|
||||||
|
|
||||||
|
|
||||||
From within a ``--no-site-packages`` virtualenv (i.e. the default kind)::
|
|
||||||
|
|
||||||
$ pip install --user SomePackage
|
|
||||||
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
|
|
||||||
|
|
||||||
|
|
||||||
From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3`` is already installed in the virtualenv::
|
|
||||||
|
|
||||||
$ pip install --user SomePackage==0.4
|
|
||||||
Will not install to the user site because it will lack sys.path precedence
|
|
||||||
|
|
||||||
|
|
||||||
From within a real python, where ``SomePackage`` is *not* installed globally::
|
|
||||||
|
|
||||||
$ pip install --user SomePackage
|
|
||||||
[...]
|
|
||||||
Successfully installed SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
From within a real python, where ``SomePackage`` *is* installed globally, but is *not* the latest version::
|
|
||||||
|
|
||||||
$ pip install --user SomePackage
|
|
||||||
[...]
|
|
||||||
Requirement already satisfied (use --upgrade to upgrade)
|
|
||||||
|
|
||||||
$ pip install --user --upgrade SomePackage
|
|
||||||
[...]
|
|
||||||
Successfully installed SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
From within a real python, where ``SomePackage`` *is* installed globally, and is the latest version::
|
|
||||||
|
|
||||||
$ pip install --user SomePackage
|
|
||||||
[...]
|
|
||||||
Requirement already satisfied (use --upgrade to upgrade)
|
|
||||||
|
|
||||||
$ pip install --user --upgrade SomePackage
|
|
||||||
[...]
|
|
||||||
Requirement already up-to-date: SomePackage
|
|
||||||
|
|
||||||
# force the install
|
|
||||||
$ pip install --user --ignore-installed SomePackage
|
|
||||||
[...]
|
|
||||||
Successfully installed SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Controlling setup_requires
|
|
||||||
**************************
|
|
||||||
|
|
||||||
Setuptools offers the ``setup_requires``
|
|
||||||
`setup() keyword <http://pythonhosted.org/setuptools/setuptools.html#new-and-changed-setup-keywords>`_
|
|
||||||
for specifying dependencies that need to be present in order for the `setup.py` script to run.
|
|
||||||
Internally, Setuptools uses ``easy_install`` to fulfill these dependencies.
|
|
||||||
|
|
||||||
pip has no way to control how these dependencies are located.
|
|
||||||
None of the :ref:`Package Index Options <Package Index Options>` have an effect.
|
|
||||||
|
|
||||||
The solution is to configure a "system" or "personal"
|
|
||||||
`Distutils configuration file <http://docs.python.org/2/install/index.html#distutils-configuration-files>`_
|
|
||||||
to manage the fulfillment.
|
|
||||||
|
|
||||||
For example, to have the dependency located at an alternate index, add this:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
[easy_install]
|
|
||||||
index_url = https://my.index-mirror.com
|
|
||||||
|
|
||||||
To have the dependency located from a local directory and not crawl PyPI, add this:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
[easy_install]
|
|
||||||
allow_hosts = ''
|
|
||||||
find_links = file:///path/to/local/archives
|
|
||||||
|
|
||||||
|
|
||||||
Upgrading from distribute to setuptools
|
|
||||||
***************************************
|
|
||||||
|
|
||||||
`distribute`_ has now been merged into `setuptools`_, and it is recommended to upgrade to setuptools when possible.
|
|
||||||
|
|
||||||
To upgrade from `distribute`_ to `setuptools`_ using pip, run::
|
|
||||||
|
|
||||||
pip install --upgrade setuptools
|
|
||||||
|
|
||||||
"ImportError: No module named setuptools"
|
|
||||||
-----------------------------------------
|
|
||||||
|
|
||||||
Although using the upgrade command above works in isolation, it's possible to get
|
|
||||||
"ImportError: No module named setuptools" when using pip<1.4 to upgrade a
|
|
||||||
package that depends on setuptools or distribute.
|
|
||||||
|
|
||||||
e.g. when running a command like this: `pip install --upgrade pyramid`
|
|
||||||
|
|
||||||
Solution
|
|
||||||
~~~~~~~~
|
|
||||||
|
|
||||||
To prevent the problem in *new* environments (that aren't broken yet):
|
|
||||||
|
|
||||||
* Option 1:
|
|
||||||
|
|
||||||
* *First* run `pip install -U setuptools`,
|
|
||||||
* *Then* run the command to upgrade your package (e.g. `pip install --upgrade pyramid`)
|
|
||||||
|
|
||||||
* Option 2:
|
|
||||||
|
|
||||||
* Upgrade pip using :ref:`get-pip <get-pip>`
|
|
||||||
* *Then* run the command to upgrade your package (e.g. `pip install --upgrade pyramid`)
|
|
||||||
|
|
||||||
To fix the problem once it's occurred, you'll need to manually install the new
|
|
||||||
setuptools, then rerun the upgrade that failed.
|
|
||||||
|
|
||||||
1. Download `ez_setup.py` (https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py)
|
|
||||||
2. Run `python ez_setup.py`
|
|
||||||
3. Then rerun your upgrade (e.g. `pip install --upgrade pyramid`)
|
|
||||||
|
|
||||||
|
|
||||||
Cause
|
|
||||||
~~~~~
|
|
||||||
|
|
||||||
distribute-0.7.3 is just an empty wrapper that only serves to require the new
|
|
||||||
setuptools (setuptools>=0.7) so that it will be installed. (If you don't know
|
|
||||||
yet, the "new setuptools" is a merge of distribute and setuptools back into one
|
|
||||||
project).
|
|
||||||
|
|
||||||
distribute-0.7.3 does its job well, when the upgrade is done in isolation.
|
|
||||||
E.g. if you're currently on distribute-0.6.X, then running `pip install -U
|
|
||||||
setuptools` works fine to upgrade you to setuptools>=0.7.
|
|
||||||
|
|
||||||
The problem occurs when:
|
|
||||||
|
|
||||||
1. you are currently using an older distribute (i.e. 0.6.X)
|
|
||||||
2. and you try to use pip to upgrade a package that *depends* on setuptools or
|
|
||||||
distribute.
|
|
||||||
|
|
||||||
As part of the upgrade process, pip builds an install list that ends up
|
|
||||||
including distribute-0.7.3 and setuptools>=0.7 , but they can end up being
|
|
||||||
separated by other dependencies in the list, so what can happen is this:
|
|
||||||
|
|
||||||
1. pip uninstalls the existing distribute
|
|
||||||
2. pip installs distribute-0.7.3 (which has no importable setuptools, that pip
|
|
||||||
*needs* internally to function)
|
|
||||||
3. pip moves on to install another dependency (before setuptools>=0.7) and is
|
|
||||||
unable to proceed without the setuptools package
|
|
||||||
|
|
||||||
Note that pip v1.4 has fixes to prevent this. distribute-0.7.3 (or
|
|
||||||
setuptools>=0.7) by themselves cannot prevent this kind of problem.
|
|
||||||
|
|
||||||
.. _setuptools: https://pypi.python.org/pypi/setuptools
|
|
||||||
.. _distribute: https://pypi.python.org/pypi/distribute
|
|
||||||
.. _PyPI: https://pypi.python.org
|
|
||||||
|
|
69
docs/distribute_setuptools.rst
Normal file
69
docs/distribute_setuptools.rst
Normal file
|
@ -0,0 +1,69 @@
|
||||||
|
:orphan:
|
||||||
|
|
||||||
|
"ImportError: No module named setuptools"
|
||||||
|
+++++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Although using ``pip install --upgrade setuptools`` to upgrade from distribute
|
||||||
|
to setuptools works in isolation, it's possible to get "ImportError: No module
|
||||||
|
named setuptools" when using pip<1.4 to upgrade a package that depends on
|
||||||
|
setuptools or distribute.
|
||||||
|
|
||||||
|
e.g. when running a command like this: `pip install --upgrade pyramid`
|
||||||
|
|
||||||
|
Solution
|
||||||
|
~~~~~~~~
|
||||||
|
|
||||||
|
To prevent the problem in *new* environments (that aren't broken yet):
|
||||||
|
|
||||||
|
* Option 1:
|
||||||
|
|
||||||
|
* *First* run `pip install -U setuptools`,
|
||||||
|
* *Then* run the command to upgrade your package (e.g. `pip install --upgrade pyramid`)
|
||||||
|
|
||||||
|
* Option 2:
|
||||||
|
|
||||||
|
* Upgrade pip using :ref:`get-pip <get-pip>`
|
||||||
|
* *Then* run the command to upgrade your package (e.g. `pip install --upgrade pyramid`)
|
||||||
|
|
||||||
|
To fix the problem once it's occurred, you'll need to manually install the new
|
||||||
|
setuptools, then rerun the upgrade that failed.
|
||||||
|
|
||||||
|
1. Download `ez_setup.py` (https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py)
|
||||||
|
2. Run `python ez_setup.py`
|
||||||
|
3. Then rerun your upgrade (e.g. `pip install --upgrade pyramid`)
|
||||||
|
|
||||||
|
|
||||||
|
Cause
|
||||||
|
~~~~~
|
||||||
|
|
||||||
|
distribute-0.7.3 is just an empty wrapper that only serves to require the new
|
||||||
|
setuptools (setuptools>=0.7) so that it will be installed. (If you don't know
|
||||||
|
yet, the "new setuptools" is a merge of distribute and setuptools back into one
|
||||||
|
project).
|
||||||
|
|
||||||
|
distribute-0.7.3 does its job well, when the upgrade is done in isolation.
|
||||||
|
E.g. if you're currently on distribute-0.6.X, then running `pip install -U
|
||||||
|
setuptools` works fine to upgrade you to setuptools>=0.7.
|
||||||
|
|
||||||
|
The problem occurs when:
|
||||||
|
|
||||||
|
1. you are currently using an older distribute (i.e. 0.6.X)
|
||||||
|
2. and you try to use pip to upgrade a package that *depends* on setuptools or
|
||||||
|
distribute.
|
||||||
|
|
||||||
|
As part of the upgrade process, pip builds an install list that ends up
|
||||||
|
including distribute-0.7.3 and setuptools>=0.7 , but they can end up being
|
||||||
|
separated by other dependencies in the list, so what can happen is this:
|
||||||
|
|
||||||
|
1. pip uninstalls the existing distribute
|
||||||
|
2. pip installs distribute-0.7.3 (which has no importable setuptools, that pip
|
||||||
|
*needs* internally to function)
|
||||||
|
3. pip moves on to install another dependency (before setuptools>=0.7) and is
|
||||||
|
unable to proceed without the setuptools package
|
||||||
|
|
||||||
|
Note that pip v1.4 has fixes to prevent this. distribute-0.7.3 (or
|
||||||
|
setuptools>=0.7) by themselves cannot prevent this kind of problem.
|
||||||
|
|
||||||
|
|
||||||
|
.. _setuptools: https://pypi.python.org/pypi/setuptools
|
||||||
|
.. _distribute: https://pypi.python.org/pypi/distribute
|
|
@ -1,26 +1,25 @@
|
||||||
pip
|
pip
|
||||||
===
|
===
|
||||||
|
|
||||||
A tool for installing and managing Python packages.
|
|
||||||
|
|
||||||
`User list <http://groups.google.com/group/python-virtualenv>`_ |
|
`User list <http://groups.google.com/group/python-virtualenv>`_ |
|
||||||
`Dev list <http://groups.google.com/group/pypa-dev>`_ |
|
`Dev list <http://groups.google.com/group/pypa-dev>`_ |
|
||||||
`Issues <https://github.com/pypa/pip/issues>`_ |
|
|
||||||
`Github <https://github.com/pypa/pip>`_ |
|
`Github <https://github.com/pypa/pip>`_ |
|
||||||
`PyPI <https://pypi.python.org/pypi/pip/>`_ |
|
`PyPI <https://pypi.python.org/pypi/pip/>`_ |
|
||||||
irc:#pip
|
User IRC: #pip |
|
||||||
|
Dev IRC: #pypa
|
||||||
|
|
||||||
|
The `PyPA recommended
|
||||||
|
<https://python-packaging-user-guide.readthedocs.org/en/latest/current.html>`_
|
||||||
|
tool for installing and managing Python packages.
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
quickstart
|
quickstart
|
||||||
installing
|
installing
|
||||||
usage
|
user_guide
|
||||||
cookbook
|
reference/index
|
||||||
logic
|
|
||||||
configuration
|
|
||||||
other-tools
|
|
||||||
development
|
development
|
||||||
news
|
news
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -27,11 +27,10 @@ Then run the following (which may require administrator access)::
|
||||||
|
|
||||||
$ python get-pip.py
|
$ python get-pip.py
|
||||||
|
|
||||||
.. note::
|
If `setuptools`_ (or `distribute`_) is not already installed, ``get-pip.py`` will
|
||||||
|
install `setuptools`_ for you. [2]_
|
||||||
|
|
||||||
Beginning with v1.5.1, pip does not require `setuptools`_ prior to running
|
To upgrade an existing `setuptools`_ (or `distribute`_), run ``pip install -U setuptools`` [3]_
|
||||||
`get-pip.py`. Additionally, if `setuptools`_ (or `distribute`_) is not
|
|
||||||
already installed, `get-pip.py` will install `setuptools`_ for you.
|
|
||||||
|
|
||||||
|
|
||||||
Using Package Managers
|
Using Package Managers
|
||||||
|
@ -54,7 +53,14 @@ On Fedora::
|
||||||
tool like `curl` that verifies SSL certificates when downloading from
|
tool like `curl` that verifies SSL certificates when downloading from
|
||||||
https URLs.
|
https URLs.
|
||||||
|
|
||||||
|
.. [2] Beginning with pip v1.5.1, ``get-pip.py`` stopped requiring setuptools to
|
||||||
|
be installed first.
|
||||||
|
|
||||||
|
.. [3] Although using ``pip install --upgrade setuptools`` to upgrade from
|
||||||
|
distribute to setuptools works in isolation, it's possible to get
|
||||||
|
"ImportError: No module named setuptools" when using pip<1.4 to upgrade a
|
||||||
|
package that depends on setuptools or distribute. See :doc:`here for
|
||||||
|
details <distribute_setuptools>`.
|
||||||
|
|
||||||
.. _setuptools: https://pypi.python.org/pypi/setuptools
|
.. _setuptools: https://pypi.python.org/pypi/setuptools
|
||||||
.. _distribute: https://pypi.python.org/pypi/distribute
|
.. _distribute: https://pypi.python.org/pypi/distribute
|
||||||
|
|
||||||
|
|
||||||
|
|
341
docs/logic.rst
341
docs/logic.rst
|
@ -1,345 +1,8 @@
|
||||||
.. _`pip logic`:
|
:orphan:
|
||||||
|
|
||||||
================
|
================
|
||||||
Internal Details
|
Internal Details
|
||||||
================
|
================
|
||||||
|
|
||||||
.. _`Requirements File Format`:
|
This content is now covered in the :doc:`Reference Guide <reference/index>`
|
||||||
|
|
||||||
Requirements File Format
|
|
||||||
========================
|
|
||||||
|
|
||||||
Each line of the requirements file indicates something to be installed,
|
|
||||||
and like arguments to :ref:`pip install`, the following forms are supported::
|
|
||||||
|
|
||||||
<requirement specifier>
|
|
||||||
<archive url/path>
|
|
||||||
[-e] <local project path>
|
|
||||||
[-e] <vcs project url>
|
|
||||||
|
|
||||||
See the :ref:`pip install Examples<pip install Examples>` for examples of all these forms.
|
|
||||||
|
|
||||||
A line beginning with ``#`` is treated as a comment and ignored.
|
|
||||||
|
|
||||||
Additionally, the following :ref:`Package Index Options <Package Index Options>` are supported
|
|
||||||
|
|
||||||
* :ref:`-i, --index-url <--index-url>`
|
|
||||||
* :ref:`--extra-index-url <--extra-index-url>`
|
|
||||||
* :ref:`--no-index <--no-index>`
|
|
||||||
* :ref:`-f, --find-links <--find-links>`
|
|
||||||
* :ref:`--allow-external <--allow-external>`
|
|
||||||
* :ref:`--allow-all-external <--allow-external>`
|
|
||||||
* :ref:`--allow-unverified <--allow-unverified>`
|
|
||||||
|
|
||||||
For example, to specify :ref:`--no-index <--no-index>` and 2 :ref:`--find-links <--find-links>` locations:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
--no-index
|
|
||||||
--find-links /my/local/archives
|
|
||||||
--find-links http://some.archives.com/archives
|
|
||||||
|
|
||||||
|
|
||||||
Lastly, if you wish, you can refer to other requirements files, like this::
|
|
||||||
|
|
||||||
-r more_requirements.txt
|
|
||||||
|
|
||||||
.. _`Requirement Specifiers`:
|
|
||||||
|
|
||||||
Requirement Specifiers
|
|
||||||
======================
|
|
||||||
|
|
||||||
pip supports installing from "requirement specifiers" as implemented in
|
|
||||||
`pkg_resources Requirements <http://packages.python.org/setuptools/pkg_resources.html#requirement-objects>`_
|
|
||||||
|
|
||||||
Some Examples:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
'FooProject >= 1.2'
|
|
||||||
Fizzy [foo, bar]
|
|
||||||
'PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1'
|
|
||||||
SomethingWhoseVersionIDontCareAbout
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Use single or double quotes around specifiers to avoid ``>`` and ``<`` being interpreted as shell redirects. e.g. ``pip install 'FooProject>=1.2'``.
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Logging`:
|
|
||||||
|
|
||||||
Logging
|
|
||||||
=======
|
|
||||||
|
|
||||||
Console logging
|
|
||||||
~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
pip offers :ref:`-v, --verbose <--verbose>` and :ref:`-q, --quiet <--quiet>`
|
|
||||||
to control the console log level. Each option can be used multiple times and
|
|
||||||
used together. One ``-v`` increases the verbosity by one, whereas one ``-q`` decreases it by
|
|
||||||
one.
|
|
||||||
|
|
||||||
The series of log levels, in order, are as follows::
|
|
||||||
|
|
||||||
VERBOSE_DEBUG, DEBUG, INFO, NOTIFY, WARN, ERROR, FATAL
|
|
||||||
|
|
||||||
``NOTIFY`` is the default level.
|
|
||||||
|
|
||||||
A few examples on how the parameters work to affect the level:
|
|
||||||
|
|
||||||
* specifying nothing results in ``NOTIFY``
|
|
||||||
* ``-v`` results in ``INFO``
|
|
||||||
* ``-vv`` results in ``DEBUG``
|
|
||||||
* ``-q`` results in ``WARN``
|
|
||||||
* ``-vq`` results in ``NOTIFY``
|
|
||||||
|
|
||||||
The most practical use case for users is either ``-v`` or ``-vv`` to see
|
|
||||||
additional logging to help troubleshoot an issue.
|
|
||||||
|
|
||||||
|
|
||||||
.. _`FileLogging`:
|
|
||||||
|
|
||||||
File logging
|
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
pip offers the :ref:`--log <--log>` option for specifying a file where a maximum
|
|
||||||
verbosity log will be kept. This option is empty by default. This log appends
|
|
||||||
to previous logging.
|
|
||||||
|
|
||||||
Additionally, when commands fail (i.e. return a non-zero exit code), pip writes
|
|
||||||
a "failure log" for the failed command. This log overwrites previous
|
|
||||||
logging. The default location is as follows:
|
|
||||||
|
|
||||||
* On Unix and Mac OS X: :file:`$HOME/.pip/pip.log`
|
|
||||||
* On Windows, the configuration file is: :file:`%HOME%\\pip\\pip.log`
|
|
||||||
|
|
||||||
The option for the failure log, is :ref:`--log-file <--log-file>`.
|
|
||||||
|
|
||||||
Both logs add a line per execution to specify the date and what pip executable wrote the log.
|
|
||||||
|
|
||||||
Like all pip options, ``--log`` and ``log-file``, can also be set as an environment
|
|
||||||
variable, or placed into the pip config file. See the :ref:`Configuration`
|
|
||||||
section.
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Pre Release Versions`:
|
|
||||||
|
|
||||||
Pre-release Versions
|
|
||||||
====================
|
|
||||||
|
|
||||||
Starting with v1.4, pip will only install stable versions as specified by `PEP426`_ by default. If
|
|
||||||
a version cannot be parsed as a compliant `PEP426`_ version then it is assumed
|
|
||||||
to be a pre-release.
|
|
||||||
|
|
||||||
If a Requirement specifier includes a pre-release or development version (e.g. ``>=0.0.dev0``) then
|
|
||||||
pip will allow pre-release and development versions for that requirement. This does not include
|
|
||||||
the != flag.
|
|
||||||
|
|
||||||
The ``pip install`` command also supports a :ref:`--pre <install_--pre>` flag that will enable
|
|
||||||
installing pre-releases and development releases.
|
|
||||||
|
|
||||||
|
|
||||||
.. _PEP426: http://www.python.org/dev/peps/pep-0426
|
|
||||||
|
|
||||||
.. _`Externally Hosted Files`:
|
|
||||||
|
|
||||||
Externally Hosted Files
|
|
||||||
=======================
|
|
||||||
|
|
||||||
Starting with v1.4, pip will warn about installing any file that does not come
|
|
||||||
from the primary index. As of version 1.5, pip defaults to ignoring these files
|
|
||||||
unless asked to consider them.
|
|
||||||
|
|
||||||
The ``pip install`` command supports a
|
|
||||||
:ref:`--allow-external PROJECT <--allow-external>` option that will enable
|
|
||||||
installing links that are linked directly from the simple index but to an
|
|
||||||
external host that also have a supported hash fragment. Externally hosted
|
|
||||||
files for all projects may be enabled using the
|
|
||||||
:ref:`--allow-all-external <--allow-all-external>` flag to the ``pip install``
|
|
||||||
command.
|
|
||||||
|
|
||||||
The ``pip install`` command also supports a
|
|
||||||
:ref:`--allow-unverified PROJECT <--allow-unverified>` option that will enable
|
|
||||||
installing insecurely linked files. These are either directly linked (as above)
|
|
||||||
files without a hash, or files that are linked from either the home page or the
|
|
||||||
download url of a package.
|
|
||||||
|
|
||||||
These options can be used in a requirements file. Assuming some fictional
|
|
||||||
`ExternalPackage` that is hosted external and unverified, then your requirements
|
|
||||||
file would be like so::
|
|
||||||
|
|
||||||
--allow-external ExternalPackage
|
|
||||||
--allow-unverified ExternalPackage
|
|
||||||
ExternalPackage
|
|
||||||
|
|
||||||
|
|
||||||
.. _`VCS Support`:
|
|
||||||
|
|
||||||
VCS Support
|
|
||||||
===========
|
|
||||||
|
|
||||||
pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects the type of VCS using url prefixes: "git+", "hg+", "bzr+", "svn+".
|
|
||||||
|
|
||||||
pip requires a working VCS command on your path: git, hg, svn, or bzr.
|
|
||||||
|
|
||||||
VCS projects can be installed in :ref:`editable mode <editable-installs>` (using the :ref:`--editable <install_--editable>` option) or not.
|
|
||||||
|
|
||||||
* For editable installs, the clone location by default is "<venv path>/src/SomeProject" in virtual environments, and "<cwd>/src/SomeProject" for global installs.
|
|
||||||
The :ref:`--src <install_--src>` option can be used to modify this location.
|
|
||||||
* For non-editable installs, the project is built locally in a temp dir and then installed normally.
|
|
||||||
|
|
||||||
The url suffix "egg=<project name>" is used by pip in it's dependency logic to identify the project prior to pip downloading and analyzing the metadata.
|
|
||||||
|
|
||||||
Git
|
|
||||||
~~~
|
|
||||||
|
|
||||||
pip currently supports cloning over ``git``, ``git+https`` and ``git+ssh``:
|
|
||||||
|
|
||||||
Here are the supported forms::
|
|
||||||
|
|
||||||
[-e] git+git://git.myproject.org/MyProject#egg=MyProject
|
|
||||||
[-e] git+https://git.myproject.org/MyProject#egg=MyProject
|
|
||||||
[-e] git+ssh://git.myproject.org/MyProject#egg=MyProject
|
|
||||||
-e git+git@git.myproject.org:MyProject#egg=MyProject
|
|
||||||
|
|
||||||
Passing branch names, a commit hash or a tag name is possible like so::
|
|
||||||
|
|
||||||
[-e] git://git.myproject.org/MyProject.git@master#egg=MyProject
|
|
||||||
[-e] git://git.myproject.org/MyProject.git@v1.0#egg=MyProject
|
|
||||||
[-e] git://git.myproject.org/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
|
|
||||||
|
|
||||||
Mercurial
|
|
||||||
~~~~~~~~~
|
|
||||||
|
|
||||||
The supported schemes are: ``hg+http``, ``hg+https``,
|
|
||||||
``hg+static-http`` and ``hg+ssh``.
|
|
||||||
|
|
||||||
Here are the supported forms::
|
|
||||||
|
|
||||||
[-e] hg+http://hg.myproject.org/MyProject#egg=MyProject
|
|
||||||
[-e] hg+https://hg.myproject.org/MyProject#egg=MyProject
|
|
||||||
[-e] hg+ssh://hg.myproject.org/MyProject#egg=MyProject
|
|
||||||
|
|
||||||
You can also specify a revision number, a revision hash, a tag name or a local
|
|
||||||
branch name like so::
|
|
||||||
|
|
||||||
[-e] hg+http://hg.myproject.org/MyProject@da39a3ee5e6b#egg=MyProject
|
|
||||||
[-e] hg+http://hg.myproject.org/MyProject@2019#egg=MyProject
|
|
||||||
[-e] hg+http://hg.myproject.org/MyProject@v1.0#egg=MyProject
|
|
||||||
[-e] hg+http://hg.myproject.org/MyProject@special_feature#egg=MyProject
|
|
||||||
|
|
||||||
Subversion
|
|
||||||
~~~~~~~~~~
|
|
||||||
|
|
||||||
pip supports the URL schemes ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``, ``svn+ssh``.
|
|
||||||
|
|
||||||
You can also give specific revisions to an SVN URL, like so::
|
|
||||||
|
|
||||||
[-e] svn+svn://svn.myproject.org/svn/MyProject#egg=MyProject
|
|
||||||
[-e] svn+http://svn.myproject.org/svn/MyProject/trunk@2019#egg=MyProject
|
|
||||||
|
|
||||||
which will check out revision 2019. ``@{20080101}`` would also check
|
|
||||||
out the revision from 2008-01-01. You can only check out specific
|
|
||||||
revisions using ``-e svn+...``.
|
|
||||||
|
|
||||||
Bazaar
|
|
||||||
~~~~~~
|
|
||||||
|
|
||||||
pip supports Bazaar using the ``bzr+http``, ``bzr+https``, ``bzr+ssh``,
|
|
||||||
``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` schemes.
|
|
||||||
|
|
||||||
Here are the supported forms::
|
|
||||||
|
|
||||||
[-e] bzr+http://bzr.myproject.org/MyProject/trunk#egg=MyProject
|
|
||||||
[-e] bzr+sftp://user@myproject.org/MyProject/trunk#egg=MyProject
|
|
||||||
[-e] bzr+ssh://user@myproject.org/MyProject/trunk#egg=MyProject
|
|
||||||
[-e] bzr+ftp://user@myproject.org/MyProject/trunk#egg=MyProject
|
|
||||||
[-e] bzr+lp:MyProject#egg=MyProject
|
|
||||||
|
|
||||||
Tags or revisions can be installed like so::
|
|
||||||
|
|
||||||
[-e] bzr+https://bzr.myproject.org/MyProject/trunk@2019#egg=MyProject
|
|
||||||
[-e] bzr+http://bzr.myproject.org/MyProject/trunk@v1.0#egg=MyProject
|
|
||||||
|
|
||||||
|
|
||||||
Finding Packages
|
|
||||||
================
|
|
||||||
|
|
||||||
pip searches for packages on `PyPI <http://pypi.python.org>`_ using the
|
|
||||||
`http simple interface <http://pypi.python.org/simple>`_,
|
|
||||||
which is documented `here <http://packages.python.org/setuptools/easy_install.html#package-index-api>`_
|
|
||||||
and `there <http://www.python.org/dev/peps/pep-0301/>`_
|
|
||||||
|
|
||||||
pip offers a set of :ref:`Package Index Options <Package Index Options>` for modifying how packages are found.
|
|
||||||
|
|
||||||
See the :ref:`pip install Examples<pip install Examples>`.
|
|
||||||
|
|
||||||
|
|
||||||
.. _`SSL Certificate Verification`:
|
|
||||||
|
|
||||||
SSL Certificate Verification
|
|
||||||
============================
|
|
||||||
|
|
||||||
Starting with v1.3, pip provides SSL certificate verification over https, for the purpose
|
|
||||||
of providing secure, certified downloads from PyPI.
|
|
||||||
|
|
||||||
|
|
||||||
Hash Verification
|
|
||||||
=================
|
|
||||||
|
|
||||||
PyPI provides md5 hashes in the hash fragment of package download urls.
|
|
||||||
|
|
||||||
pip supports checking 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).
|
|
||||||
|
|
||||||
This check is only intended to provide basic download corruption protection.
|
|
||||||
It is not intended to provide security against tampering. For that,
|
|
||||||
see :ref:`SSL Certificate Verification`
|
|
||||||
|
|
||||||
|
|
||||||
Download Cache
|
|
||||||
==============
|
|
||||||
|
|
||||||
pip offers a :ref:`--download-cache <install_--download-cache>` option for installs to prevent redundant downloads of archives from PyPI.
|
|
||||||
|
|
||||||
The point of this cache is *not* to circumvent the index crawling process, but to *just* prevent redundant downloads.
|
|
||||||
|
|
||||||
Items are stored in this cache based on the url the archive was found at, not simply the archive name.
|
|
||||||
|
|
||||||
If you want a fast/local install solution that circumvents crawling PyPI, see the :ref:`Fast & Local Installs` Cookbook entry.
|
|
||||||
|
|
||||||
Like all options, :ref:`--download-cache <install_--download-cache>`, can also be set as an environment variable, or placed into the pip config file.
|
|
||||||
See the :ref:`Configuration` section.
|
|
||||||
|
|
||||||
|
|
||||||
.. _`editable-installs`:
|
|
||||||
|
|
||||||
"Editable" Installs
|
|
||||||
===================
|
|
||||||
|
|
||||||
"Editable" installs are fundamentally `"setuptools develop mode" <http://packages.python.org/setuptools/setuptools.html#development-mode>`_ installs.
|
|
||||||
|
|
||||||
You can install local projects or VCS projects in "editable" mode::
|
|
||||||
|
|
||||||
$ pip install -e path/to/SomeProject
|
|
||||||
$ pip install -e git+http://repo/my_project.git#egg=SomeProject
|
|
||||||
|
|
||||||
For local projects, the "SomeProject.egg-info" directory is created relative to the project path.
|
|
||||||
This is one advantage over just using ``setup.py develop``, which creates the "egg-info" directly relative the current working directory.
|
|
||||||
|
|
||||||
|
|
||||||
setuptools & pkg_resources
|
|
||||||
==========================
|
|
||||||
|
|
||||||
Internally, pip uses the `setuptools` package, and the `pkg_resources` module, which are available from the project, `Setuptools`_.
|
|
||||||
|
|
||||||
Here are some examples of how pip uses `setuptools` and `pkg_resources`:
|
|
||||||
|
|
||||||
* The core of pip's install process uses the `setuptools`'s "install" command.
|
|
||||||
* Editable ("-e") installs use the `setuptools`'s "develop" command.
|
|
||||||
* pip uses `pkg_resources` for version parsing, for detecting version conflicts, and to determine what projects are installed,
|
|
||||||
|
|
||||||
|
|
||||||
.. _Setuptools: http://pypi.python.org/pypi/setuptools/
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
====
|
=============
|
||||||
News
|
Release Notes
|
||||||
====
|
=============
|
||||||
|
|
||||||
.. include:: ../CHANGES.txt
|
.. include:: ../CHANGES.txt
|
||||||
|
|
|
@ -1,65 +0,0 @@
|
||||||
===========
|
|
||||||
Other tools
|
|
||||||
===========
|
|
||||||
|
|
||||||
virtualenv
|
|
||||||
----------
|
|
||||||
|
|
||||||
pip is most nutritious when used with `virtualenv
|
|
||||||
<http://pypi.python.org/pypi/virtualenv>`__. One of the reasons pip
|
|
||||||
doesn't install "multi-version" eggs is that virtualenv removes much of the need
|
|
||||||
for it. Because pip is installed by virtualenv, just use
|
|
||||||
``path/to/my/environment/bin/pip`` to install things into that
|
|
||||||
specific environment.
|
|
||||||
|
|
||||||
To tell pip to only run if there is a virtualenv currently activated,
|
|
||||||
and to bail if not, use::
|
|
||||||
|
|
||||||
export PIP_REQUIRE_VIRTUALENV=true
|
|
||||||
|
|
||||||
easy_install
|
|
||||||
------------
|
|
||||||
|
|
||||||
pip was originally written to improve on `easy_install <http://pythonhosted.org/setuptools/easy_install.html>`_ in the following ways:
|
|
||||||
|
|
||||||
* All packages are downloaded before installation. Partially-completed
|
|
||||||
installation doesn't occur as a result.
|
|
||||||
|
|
||||||
* Care is taken to present useful output on the console.
|
|
||||||
|
|
||||||
* The reasons for actions are kept track of. For instance, if a package is
|
|
||||||
being installed, pip keeps track of why that package was required.
|
|
||||||
|
|
||||||
* Error messages should be useful.
|
|
||||||
|
|
||||||
* The code is relatively concise and cohesive, making it easier to use
|
|
||||||
programmatically.
|
|
||||||
|
|
||||||
* Packages don't have to be installed as egg archives, they can be installed
|
|
||||||
flat (while keeping the egg metadata).
|
|
||||||
|
|
||||||
* Native support for other version control systems (Git, Mercurial and Bazaar)
|
|
||||||
|
|
||||||
* Uninstallation of packages.
|
|
||||||
|
|
||||||
* Simple to define fixed sets of requirements and reliably reproduce a
|
|
||||||
set of packages.
|
|
||||||
|
|
||||||
pip doesn't do everything that easy_install does. Specifically:
|
|
||||||
|
|
||||||
* It cannot install from eggs. That’s not a problem anymore though because pip
|
|
||||||
supports the superior binary `wheel format
|
|
||||||
<https://wheel.readthedocs.org/en/latest/>`_ since the 1.4 release.
|
|
||||||
|
|
||||||
* It is incompatible with some packages that extensively customize distutils
|
|
||||||
or setuptools in their ``setup.py`` files.
|
|
||||||
|
|
||||||
|
|
||||||
buildout
|
|
||||||
--------
|
|
||||||
|
|
||||||
If you are using `zc.buildout
|
|
||||||
<http://pypi.python.org/pypi/zc.buildout>`_ you should look at
|
|
||||||
`gp.recipe.pip <http://pypi.python.org/pypi/gp.recipe.pip>`_ as an
|
|
||||||
option to use pip and virtualenv in your buildouts.
|
|
||||||
|
|
|
@ -44,7 +44,7 @@ class PipOptions(rst.Directive):
|
||||||
bookmark_line = ".. _`%s_%s`:" % (cmd_name, option._long_opts[0])
|
bookmark_line = ".. _`%s_%s`:" % (cmd_name, option._long_opts[0])
|
||||||
else:
|
else:
|
||||||
bookmark_line = ".. _`%s`:" % option._long_opts[0]
|
bookmark_line = ".. _`%s`:" % option._long_opts[0]
|
||||||
line = "``"
|
line = ".. option:: "
|
||||||
if option._short_opts:
|
if option._short_opts:
|
||||||
line += option._short_opts[0]
|
line += option._short_opts[0]
|
||||||
if option._short_opts and option._long_opts:
|
if option._short_opts and option._long_opts:
|
||||||
|
@ -54,7 +54,6 @@ class PipOptions(rst.Directive):
|
||||||
if option.takes_value():
|
if option.takes_value():
|
||||||
metavar = option.metavar or option.dest.lower()
|
metavar = option.metavar or option.dest.lower()
|
||||||
line += " <%s>" % metavar.lower()
|
line += " <%s>" % metavar.lower()
|
||||||
line += '``'
|
|
||||||
#fix defaults
|
#fix defaults
|
||||||
opt_help = option.help.replace('%default', str(option.default))
|
opt_help = option.help.replace('%default', str(option.default))
|
||||||
#fix paths with sys.prefix
|
#fix paths with sys.prefix
|
||||||
|
|
|
@ -1,11 +1,13 @@
|
||||||
Quickstart
|
Quickstart
|
||||||
==========
|
==========
|
||||||
|
|
||||||
Install a package:
|
First, :doc:`Install pip <installing>`.
|
||||||
|
|
||||||
|
Install a package from `PyPI`_:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
$ pip install SomePackage==1.0
|
$ pip install SomePackage
|
||||||
[...]
|
[...]
|
||||||
Successfully installed SomePackage
|
Successfully installed SomePackage
|
||||||
|
|
||||||
|
@ -50,3 +52,5 @@ Uninstall a package:
|
||||||
Proceed (y/n)? y
|
Proceed (y/n)? y
|
||||||
Successfully uninstalled SomePackage
|
Successfully uninstalled SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
.. _PyPI: http://pypi.python.org/pypi/
|
||||||
|
|
17
docs/reference/index.rst
Normal file
17
docs/reference/index.rst
Normal file
|
@ -0,0 +1,17 @@
|
||||||
|
===============
|
||||||
|
Reference Guide
|
||||||
|
===============
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
pip
|
||||||
|
pip_install
|
||||||
|
pip_uninstall
|
||||||
|
pip_freeze
|
||||||
|
pip_list
|
||||||
|
pip_show
|
||||||
|
pip_search
|
||||||
|
pip_wheel
|
||||||
|
|
||||||
|
|
80
docs/reference/pip.rst
Normal file
80
docs/reference/pip.rst
Normal file
|
@ -0,0 +1,80 @@
|
||||||
|
|
||||||
|
pip
|
||||||
|
---
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pip <command> [options]
|
||||||
|
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
|
||||||
|
.. _`Logging`:
|
||||||
|
|
||||||
|
Logging
|
||||||
|
=======
|
||||||
|
|
||||||
|
Console logging
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
pip offers :ref:`-v, --verbose <--verbose>` and :ref:`-q, --quiet <--quiet>`
|
||||||
|
to control the console log level. Each option can be used multiple times and
|
||||||
|
used together. One ``-v`` increases the verbosity by one, whereas one ``-q`` decreases it by
|
||||||
|
one.
|
||||||
|
|
||||||
|
The series of log levels, in order, are as follows::
|
||||||
|
|
||||||
|
VERBOSE_DEBUG, DEBUG, INFO, NOTIFY, WARN, ERROR, FATAL
|
||||||
|
|
||||||
|
``NOTIFY`` is the default level.
|
||||||
|
|
||||||
|
A few examples on how the parameters work to affect the level:
|
||||||
|
|
||||||
|
* specifying nothing results in ``NOTIFY``
|
||||||
|
* ``-v`` results in ``INFO``
|
||||||
|
* ``-vv`` results in ``DEBUG``
|
||||||
|
* ``-q`` results in ``WARN``
|
||||||
|
* ``-vq`` results in ``NOTIFY``
|
||||||
|
|
||||||
|
The most practical use case for users is either ``-v`` or ``-vv`` to see
|
||||||
|
additional logging to help troubleshoot an issue.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`FileLogging`:
|
||||||
|
|
||||||
|
File logging
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
pip offers the :ref:`--log <--log>` option for specifying a file where a maximum
|
||||||
|
verbosity log will be kept. This option is empty by default. This log appends
|
||||||
|
to previous logging.
|
||||||
|
|
||||||
|
Additionally, when commands fail (i.e. return a non-zero exit code), pip writes
|
||||||
|
a "failure log" for the failed command. This log overwrites previous
|
||||||
|
logging. The default location is as follows:
|
||||||
|
|
||||||
|
* On Unix and Mac OS X: :file:`$HOME/.pip/pip.log`
|
||||||
|
* On Windows, the configuration file is: :file:`%HOME%\\pip\\pip.log`
|
||||||
|
|
||||||
|
The option for the failure log, is :ref:`--log-file <--log-file>`.
|
||||||
|
|
||||||
|
Both logs add a line per execution to specify the date and what pip executable wrote the log.
|
||||||
|
|
||||||
|
Like all pip options, ``--log`` and ``log-file``, can also be set as an environment
|
||||||
|
variable, or placed into the pip config file. See the :ref:`Configuration`
|
||||||
|
section.
|
||||||
|
|
||||||
|
.. _`General Options`:
|
||||||
|
|
||||||
|
General Options
|
||||||
|
***************
|
||||||
|
|
||||||
|
.. pip-general-options::
|
||||||
|
|
46
docs/reference/pip_freeze.rst
Normal file
46
docs/reference/pip_freeze.rst
Normal file
|
@ -0,0 +1,46 @@
|
||||||
|
|
||||||
|
.. _`pip freeze`:
|
||||||
|
|
||||||
|
pip freeze
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
.. pip-command-usage:: freeze
|
||||||
|
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. pip-command-description:: freeze
|
||||||
|
|
||||||
|
|
||||||
|
Options
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. pip-command-options:: freeze
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
********
|
||||||
|
|
||||||
|
1) Generate output suitable for a requirements file.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip freeze
|
||||||
|
Jinja2==2.6
|
||||||
|
Pygments==1.5
|
||||||
|
Sphinx==1.1.3
|
||||||
|
docutils==0.9.1
|
||||||
|
|
||||||
|
|
||||||
|
2) Generate a requirements file and then install from it in another environment.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ env1/bin/pip freeze > requirements.txt
|
||||||
|
$ env2/bin/pip install -r requirements.txt
|
439
docs/reference/pip_install.rst
Normal file
439
docs/reference/pip_install.rst
Normal file
|
@ -0,0 +1,439 @@
|
||||||
|
|
||||||
|
.. _`pip install`:
|
||||||
|
|
||||||
|
pip install
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
.. pip-command-usage:: install
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. pip-command-description:: install
|
||||||
|
|
||||||
|
|
||||||
|
.. _`Requirements File Format`:
|
||||||
|
|
||||||
|
Requirements File Format
|
||||||
|
++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Each line of the requirements file indicates something to be installed,
|
||||||
|
and like arguments to :ref:`pip install`, the following forms are supported::
|
||||||
|
|
||||||
|
<requirement specifier>
|
||||||
|
<archive url/path>
|
||||||
|
[-e] <local project path>
|
||||||
|
[-e] <vcs project url>
|
||||||
|
|
||||||
|
See the :ref:`pip install Examples<pip install Examples>` for examples of all these forms.
|
||||||
|
|
||||||
|
A line beginning with ``#`` is treated as a comment and ignored.
|
||||||
|
|
||||||
|
Additionally, the following Package Index Options are supported:
|
||||||
|
|
||||||
|
* :ref:`-i, --index-url <--index-url>`
|
||||||
|
* :ref:`--extra-index-url <--extra-index-url>`
|
||||||
|
* :ref:`--no-index <--no-index>`
|
||||||
|
* :ref:`-f, --find-links <--find-links>`
|
||||||
|
* :ref:`--allow-external <--allow-external>`
|
||||||
|
* :ref:`--allow-all-external <--allow-external>`
|
||||||
|
* :ref:`--allow-unverified <--allow-unverified>`
|
||||||
|
|
||||||
|
For example, to specify :ref:`--no-index <--no-index>` and 2 :ref:`--find-links <--find-links>` locations:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
--no-index
|
||||||
|
--find-links /my/local/archives
|
||||||
|
--find-links http://some.archives.com/archives
|
||||||
|
|
||||||
|
|
||||||
|
Lastly, if you wish, you can refer to other requirements files, like this::
|
||||||
|
|
||||||
|
-r more_requirements.txt
|
||||||
|
|
||||||
|
.. _`Requirement Specifiers`:
|
||||||
|
|
||||||
|
Requirement Specifiers
|
||||||
|
++++++++++++++++++++++
|
||||||
|
|
||||||
|
pip supports installing from "requirement specifiers" as implemented in
|
||||||
|
`pkg_resources Requirements <http://packages.python.org/setuptools/pkg_resources.html#requirement-objects>`_
|
||||||
|
|
||||||
|
Some Examples:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
'FooProject >= 1.2'
|
||||||
|
Fizzy [foo, bar]
|
||||||
|
'PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1'
|
||||||
|
SomethingWhoseVersionIDontCareAbout
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Use single or double quotes around specifiers to avoid ``>`` and ``<`` being
|
||||||
|
interpreted as shell redirects. e.g. ``pip install 'FooProject>=1.2'``.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _`Pre Release Versions`:
|
||||||
|
|
||||||
|
Pre-release Versions
|
||||||
|
++++++++++++++++++++
|
||||||
|
|
||||||
|
Starting with v1.4, pip will only install stable versions as specified by
|
||||||
|
`PEP426`_ by default. If a version cannot be parsed as a compliant `PEP426`_
|
||||||
|
version then it is assumed to be a pre-release.
|
||||||
|
|
||||||
|
If a Requirement specifier includes a pre-release or development version
|
||||||
|
(e.g. ``>=0.0.dev0``) then pip will allow pre-release and development versions
|
||||||
|
for that requirement. This does not include the != flag.
|
||||||
|
|
||||||
|
The ``pip install`` command also supports a :ref:`--pre <install_--pre>` flag
|
||||||
|
that will enable installing pre-releases and development releases.
|
||||||
|
|
||||||
|
|
||||||
|
.. _PEP426: http://www.python.org/dev/peps/pep-0426
|
||||||
|
|
||||||
|
.. _`Externally Hosted Files`:
|
||||||
|
|
||||||
|
Externally Hosted Files
|
||||||
|
+++++++++++++++++++++++
|
||||||
|
|
||||||
|
Starting with v1.4, pip will warn about installing any file that does not come
|
||||||
|
from the primary index. As of version 1.5, pip defaults to ignoring these files
|
||||||
|
unless asked to consider them.
|
||||||
|
|
||||||
|
The ``pip install`` command supports a
|
||||||
|
:ref:`--allow-external PROJECT <--allow-external>` option that will enable
|
||||||
|
installing links that are linked directly from the simple index but to an
|
||||||
|
external host that also have a supported hash fragment. Externally hosted
|
||||||
|
files for all projects may be enabled using the
|
||||||
|
:ref:`--allow-all-external <--allow-all-external>` flag to the ``pip install``
|
||||||
|
command.
|
||||||
|
|
||||||
|
The ``pip install`` command also supports a
|
||||||
|
:ref:`--allow-unverified PROJECT <--allow-unverified>` option that will enable
|
||||||
|
installing insecurely linked files. These are either directly linked (as above)
|
||||||
|
files without a hash, or files that are linked from either the home page or the
|
||||||
|
download url of a package.
|
||||||
|
|
||||||
|
These options can be used in a requirements file. Assuming some fictional
|
||||||
|
`ExternalPackage` that is hosted external and unverified, then your requirements
|
||||||
|
file would be like so::
|
||||||
|
|
||||||
|
--allow-external ExternalPackage
|
||||||
|
--allow-unverified ExternalPackage
|
||||||
|
ExternalPackage
|
||||||
|
|
||||||
|
|
||||||
|
.. _`VCS Support`:
|
||||||
|
|
||||||
|
VCS Support
|
||||||
|
+++++++++++
|
||||||
|
|
||||||
|
pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects
|
||||||
|
the type of VCS using url prefixes: "git+", "hg+", "bzr+", "svn+".
|
||||||
|
|
||||||
|
pip requires a working VCS command on your path: git, hg, svn, or bzr.
|
||||||
|
|
||||||
|
VCS projects can be installed in :ref:`editable mode <editable-installs>` (using
|
||||||
|
the :ref:`--editable <install_--editable>` option) or not.
|
||||||
|
|
||||||
|
* For editable installs, the clone location by default is "<venv
|
||||||
|
path>/src/SomeProject" in virtual environments, and "<cwd>/src/SomeProject"
|
||||||
|
for global installs. The :ref:`--src <install_--src>` option can be used to
|
||||||
|
modify this location.
|
||||||
|
* For non-editable installs, the project is built locally in a temp dir and then
|
||||||
|
installed normally.
|
||||||
|
|
||||||
|
The url suffix "egg=<project name>" is used by pip in it's dependency logic to
|
||||||
|
identify the project prior to pip downloading and analyzing the metadata.
|
||||||
|
|
||||||
|
Git
|
||||||
|
~~~
|
||||||
|
|
||||||
|
pip currently supports cloning over ``git``, ``git+https`` and ``git+ssh``:
|
||||||
|
|
||||||
|
Here are the supported forms::
|
||||||
|
|
||||||
|
[-e] git+git://git.myproject.org/MyProject#egg=MyProject
|
||||||
|
[-e] git+https://git.myproject.org/MyProject#egg=MyProject
|
||||||
|
[-e] git+ssh://git.myproject.org/MyProject#egg=MyProject
|
||||||
|
-e git+git@git.myproject.org:MyProject#egg=MyProject
|
||||||
|
|
||||||
|
Passing branch names, a commit hash or a tag name is possible like so::
|
||||||
|
|
||||||
|
[-e] git://git.myproject.org/MyProject.git@master#egg=MyProject
|
||||||
|
[-e] git://git.myproject.org/MyProject.git@v1.0#egg=MyProject
|
||||||
|
[-e] git://git.myproject.org/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
|
||||||
|
|
||||||
|
Mercurial
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
The supported schemes are: ``hg+http``, ``hg+https``,
|
||||||
|
``hg+static-http`` and ``hg+ssh``.
|
||||||
|
|
||||||
|
Here are the supported forms::
|
||||||
|
|
||||||
|
[-e] hg+http://hg.myproject.org/MyProject#egg=MyProject
|
||||||
|
[-e] hg+https://hg.myproject.org/MyProject#egg=MyProject
|
||||||
|
[-e] hg+ssh://hg.myproject.org/MyProject#egg=MyProject
|
||||||
|
|
||||||
|
You can also specify a revision number, a revision hash, a tag name or a local
|
||||||
|
branch name like so::
|
||||||
|
|
||||||
|
[-e] hg+http://hg.myproject.org/MyProject@da39a3ee5e6b#egg=MyProject
|
||||||
|
[-e] hg+http://hg.myproject.org/MyProject@2019#egg=MyProject
|
||||||
|
[-e] hg+http://hg.myproject.org/MyProject@v1.0#egg=MyProject
|
||||||
|
[-e] hg+http://hg.myproject.org/MyProject@special_feature#egg=MyProject
|
||||||
|
|
||||||
|
Subversion
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
|
pip supports the URL schemes ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``, ``svn+ssh``.
|
||||||
|
|
||||||
|
You can also give specific revisions to an SVN URL, like so::
|
||||||
|
|
||||||
|
[-e] svn+svn://svn.myproject.org/svn/MyProject#egg=MyProject
|
||||||
|
[-e] svn+http://svn.myproject.org/svn/MyProject/trunk@2019#egg=MyProject
|
||||||
|
|
||||||
|
which will check out revision 2019. ``@{20080101}`` would also check
|
||||||
|
out the revision from 2008-01-01. You can only check out specific
|
||||||
|
revisions using ``-e svn+...``.
|
||||||
|
|
||||||
|
Bazaar
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
pip supports Bazaar using the ``bzr+http``, ``bzr+https``, ``bzr+ssh``,
|
||||||
|
``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` schemes.
|
||||||
|
|
||||||
|
Here are the supported forms::
|
||||||
|
|
||||||
|
[-e] bzr+http://bzr.myproject.org/MyProject/trunk#egg=MyProject
|
||||||
|
[-e] bzr+sftp://user@myproject.org/MyProject/trunk#egg=MyProject
|
||||||
|
[-e] bzr+ssh://user@myproject.org/MyProject/trunk#egg=MyProject
|
||||||
|
[-e] bzr+ftp://user@myproject.org/MyProject/trunk#egg=MyProject
|
||||||
|
[-e] bzr+lp:MyProject#egg=MyProject
|
||||||
|
|
||||||
|
Tags or revisions can be installed like so::
|
||||||
|
|
||||||
|
[-e] bzr+https://bzr.myproject.org/MyProject/trunk@2019#egg=MyProject
|
||||||
|
[-e] bzr+http://bzr.myproject.org/MyProject/trunk@v1.0#egg=MyProject
|
||||||
|
|
||||||
|
|
||||||
|
Finding Packages
|
||||||
|
++++++++++++++++
|
||||||
|
|
||||||
|
pip searches for packages on `PyPI`_ using the
|
||||||
|
`http simple interface <http://pypi.python.org/simple>`_,
|
||||||
|
which is documented `here <http://packages.python.org/setuptools/easy_install.html#package-index-api>`_
|
||||||
|
and `there <http://www.python.org/dev/peps/pep-0301/>`_
|
||||||
|
|
||||||
|
pip offers a number of Package Index Options for modifying how packages are found.
|
||||||
|
|
||||||
|
See the :ref:`pip install Examples<pip install Examples>`.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`SSL Certificate Verification`:
|
||||||
|
|
||||||
|
SSL Certificate Verification
|
||||||
|
++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Starting with v1.3, pip provides SSL certificate verification over https, for the purpose
|
||||||
|
of providing secure, certified downloads from PyPI.
|
||||||
|
|
||||||
|
|
||||||
|
Hash Verification
|
||||||
|
+++++++++++++++++
|
||||||
|
|
||||||
|
PyPI provides md5 hashes in the hash fragment of package download urls.
|
||||||
|
|
||||||
|
pip supports checking 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).
|
||||||
|
|
||||||
|
This check is only intended to provide basic download corruption protection.
|
||||||
|
It is not intended to provide security against tampering. For that,
|
||||||
|
see :ref:`SSL Certificate Verification`
|
||||||
|
|
||||||
|
|
||||||
|
Download Cache
|
||||||
|
++++++++++++++
|
||||||
|
|
||||||
|
pip offers a :ref:`--download-cache <install_--download-cache>` option for
|
||||||
|
installs to prevent redundant downloads of archives from PyPI.
|
||||||
|
|
||||||
|
The point of this cache is *not* to circumvent the index crawling process, but
|
||||||
|
to *just* prevent redundant downloads.
|
||||||
|
|
||||||
|
Items are stored in this cache based on the url the archive was found at, not
|
||||||
|
simply the archive name.
|
||||||
|
|
||||||
|
If you want a fast/local install solution that circumvents crawling PyPI, see
|
||||||
|
the :ref:`Fast & Local Installs`.
|
||||||
|
|
||||||
|
Like all options, :ref:`--download-cache <install_--download-cache>`, can also
|
||||||
|
be set as an environment variable, or placed into the pip config file. See the
|
||||||
|
:ref:`Configuration` section.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`editable-installs`:
|
||||||
|
|
||||||
|
"Editable" Installs
|
||||||
|
+++++++++++++++++++
|
||||||
|
|
||||||
|
"Editable" installs are fundamentally `"setuptools develop mode"
|
||||||
|
<http://packages.python.org/setuptools/setuptools.html#development-mode>`_
|
||||||
|
installs.
|
||||||
|
|
||||||
|
You can install local projects or VCS projects in "editable" mode::
|
||||||
|
|
||||||
|
$ pip install -e path/to/SomeProject
|
||||||
|
$ pip install -e git+http://repo/my_project.git#egg=SomeProject
|
||||||
|
|
||||||
|
For local projects, the "SomeProject.egg-info" directory is created relative to
|
||||||
|
the project path. This is one advantage over just using ``setup.py develop``,
|
||||||
|
which creates the "egg-info" directly relative the current working directory.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Controlling setup_requires
|
||||||
|
++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
Setuptools offers the ``setup_requires`` `setup() keyword
|
||||||
|
<http://pythonhosted.org/setuptools/setuptools.html#new-and-changed-setup-keywords>`_
|
||||||
|
for specifying dependencies that need to be present in order for the `setup.py`
|
||||||
|
script to run. Internally, Setuptools uses ``easy_install`` to fulfill these
|
||||||
|
dependencies.
|
||||||
|
|
||||||
|
pip has no way to control how these dependencies are located. None of the
|
||||||
|
Package Index Options have an effect.
|
||||||
|
|
||||||
|
The solution is to configure a "system" or "personal" `Distutils configuration
|
||||||
|
file
|
||||||
|
<http://docs.python.org/2/install/index.html#distutils-configuration-files>`_ to
|
||||||
|
manage the fulfillment.
|
||||||
|
|
||||||
|
For example, to have the dependency located at an alternate index, add this:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
[easy_install]
|
||||||
|
index_url = https://my.index-mirror.com
|
||||||
|
|
||||||
|
To have the dependency located from a local directory and not crawl PyPI, add this:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
[easy_install]
|
||||||
|
allow_hosts = ''
|
||||||
|
find_links = file:///path/to/local/archives
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Options
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. pip-command-options:: install
|
||||||
|
|
||||||
|
.. pip-index-options::
|
||||||
|
|
||||||
|
|
||||||
|
.. _`pip install Examples`:
|
||||||
|
|
||||||
|
Examples
|
||||||
|
********
|
||||||
|
|
||||||
|
1) Install `SomePackage` and it's dependencies from `PyPI`_ using :ref:`Requirement Specifiers`
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install SomePackage # latest version
|
||||||
|
$ pip install SomePackage==1.0.4 # specific version
|
||||||
|
$ pip install 'SomePackage>=1.0.4' # minimum version
|
||||||
|
|
||||||
|
|
||||||
|
2) Install a list of requirements specified in a file. See the :ref:`Requirements files <Requirements Files>`.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install -r requirements.txt
|
||||||
|
|
||||||
|
|
||||||
|
3) Upgrade an already installed `SomePackage` to the latest from PyPI.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install --upgrade SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
4) Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install -e . # project in current directory
|
||||||
|
$ pip install -e path/to/project # project in another directory
|
||||||
|
|
||||||
|
|
||||||
|
5) Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support <VCS Support>` and :ref:`Editable Installs <editable-installs>`.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git
|
||||||
|
$ pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial
|
||||||
|
$ pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn
|
||||||
|
$ pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch
|
||||||
|
$ pip install -e git+https://git.repo/some_repo.git@egg=subdir&subdirectory=subdir_path # install a python package from a repo subdirectory
|
||||||
|
|
||||||
|
6) Install a package with `setuptools extras`_.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install SomePackage[PDF]
|
||||||
|
$ pip install SomePackage[PDF]==3.0
|
||||||
|
$ pip install -e .[PDF]==3.0 # editable project in current directory
|
||||||
|
|
||||||
|
|
||||||
|
7) Install a particular source archive file.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install ./downloads/SomePackage-1.0.4.tar.gz
|
||||||
|
$ pip install http://my.package.repo/SomePackage-1.0.4.zip
|
||||||
|
|
||||||
|
|
||||||
|
8) Install from alternative package repositories.
|
||||||
|
|
||||||
|
Install from a different index, and not `PyPI`_ ::
|
||||||
|
|
||||||
|
$ pip install --index-url http://my.package.repo/simple/ SomePackage
|
||||||
|
|
||||||
|
Search an additional index during install, in addition to `PyPI`_ ::
|
||||||
|
|
||||||
|
$ pip install --extra-index-url http://my.package.repo/simple SomePackage
|
||||||
|
|
||||||
|
Install from a local flat directory containing archives (and don't scan indexes)::
|
||||||
|
|
||||||
|
$ pip install --no-index --find-links=file:///local/dir/ SomePackage
|
||||||
|
$ pip install --no-index --find-links=/local/dir/ SomePackage
|
||||||
|
$ pip install --no-index --find-links=relative/dir/ SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
9) Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install --pre SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _PyPI: http://pypi.python.org/pypi/
|
||||||
|
.. _setuptools extras: http://packages.python.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
|
45
docs/reference/pip_list.rst
Normal file
45
docs/reference/pip_list.rst
Normal file
|
@ -0,0 +1,45 @@
|
||||||
|
.. _`pip list`:
|
||||||
|
|
||||||
|
pip list
|
||||||
|
---------
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
.. pip-command-usage:: list
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. pip-command-description:: list
|
||||||
|
|
||||||
|
Options
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. pip-command-options:: list
|
||||||
|
|
||||||
|
.. pip-index-options::
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
********
|
||||||
|
|
||||||
|
1) List installed packages.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip list
|
||||||
|
Pygments (1.5)
|
||||||
|
docutils (0.9.1)
|
||||||
|
Sphinx (1.1.2)
|
||||||
|
Jinja2 (2.6)
|
||||||
|
|
||||||
|
2) List outdated packages (excluding editables), and the latest version available
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip list --outdated
|
||||||
|
docutils (Current: 0.9.1 Latest: 0.10)
|
||||||
|
Sphinx (Current: 1.1.2 Latest: 1.1.3)
|
36
docs/reference/pip_search.rst
Normal file
36
docs/reference/pip_search.rst
Normal file
|
@ -0,0 +1,36 @@
|
||||||
|
.. _`pip search`:
|
||||||
|
|
||||||
|
pip search
|
||||||
|
----------
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
.. pip-command-usage:: search
|
||||||
|
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. pip-command-description:: search
|
||||||
|
|
||||||
|
Options
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. pip-command-options:: search
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
********
|
||||||
|
|
||||||
|
1. Search for "peppercorn"
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip search peppercorn
|
||||||
|
pepperedform - Helpers for using peppercorn with formprocess.
|
||||||
|
peppercorn - A library for converting a token stream into [...]
|
||||||
|
|
||||||
|
.. _`pip wheel`:
|
37
docs/reference/pip_show.rst
Normal file
37
docs/reference/pip_show.rst
Normal file
|
@ -0,0 +1,37 @@
|
||||||
|
.. _`pip show`:
|
||||||
|
|
||||||
|
pip show
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
.. pip-command-usage:: show
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. pip-command-description:: show
|
||||||
|
|
||||||
|
|
||||||
|
Options
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. pip-command-options:: show
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
********
|
||||||
|
|
||||||
|
1. Show information about a package:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip show sphinx
|
||||||
|
---
|
||||||
|
Name: Sphinx
|
||||||
|
Version: 1.1.3
|
||||||
|
Location: /my/env/lib/pythonx.x/site-packages
|
||||||
|
Requires: Pygments, Jinja2, docutils
|
37
docs/reference/pip_uninstall.rst
Normal file
37
docs/reference/pip_uninstall.rst
Normal file
|
@ -0,0 +1,37 @@
|
||||||
|
.. _`pip uninstall`:
|
||||||
|
|
||||||
|
pip uninstall
|
||||||
|
-------------
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
.. pip-command-usage:: uninstall
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. pip-command-description:: uninstall
|
||||||
|
|
||||||
|
Options
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. pip-command-options:: uninstall
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
********
|
||||||
|
|
||||||
|
1) Uninstall a package.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip uninstall simplejson
|
||||||
|
Uninstalling simplejson:
|
||||||
|
/home/me/env/lib/python2.7/site-packages/simplejson
|
||||||
|
/home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info
|
||||||
|
Proceed (y/n)? y
|
||||||
|
Successfully uninstalled simplejson
|
||||||
|
|
37
docs/reference/pip_wheel.rst
Normal file
37
docs/reference/pip_wheel.rst
Normal file
|
@ -0,0 +1,37 @@
|
||||||
|
|
||||||
|
.. _`pip wheel`:
|
||||||
|
|
||||||
|
pip wheel
|
||||||
|
---------
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
.. pip-command-usage:: wheel
|
||||||
|
|
||||||
|
|
||||||
|
Description
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. pip-command-description:: wheel
|
||||||
|
|
||||||
|
|
||||||
|
Options
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. pip-command-options:: wheel
|
||||||
|
|
||||||
|
.. pip-index-options::
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
********
|
||||||
|
|
||||||
|
1. Build wheels for a requirement (and all its dependencies), and then install
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage
|
||||||
|
$ pip install --no-index --find-links=/tmp/wheelhouse SomePackage
|
436
docs/usage.rst
436
docs/usage.rst
|
@ -1,438 +1,8 @@
|
||||||
|
:orphan:
|
||||||
|
|
||||||
==========
|
==========
|
||||||
Usage
|
Usage
|
||||||
==========
|
==========
|
||||||
|
|
||||||
pip
|
The "Usage" section is now covered in the :doc:`Reference Guide <reference/index>`
|
||||||
---
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pip <command> [options]
|
|
||||||
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
.. _`General Options`:
|
|
||||||
|
|
||||||
**General Options:**
|
|
||||||
|
|
||||||
.. pip-general-options::
|
|
||||||
|
|
||||||
|
|
||||||
.. _`Package Index Options`:
|
|
||||||
|
|
||||||
**Package Index Options:**
|
|
||||||
|
|
||||||
.. pip-index-options::
|
|
||||||
|
|
||||||
|
|
||||||
.. _`pip install`:
|
|
||||||
|
|
||||||
pip install
|
|
||||||
-----------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
********
|
|
||||||
|
|
||||||
.. pip-command-usage:: install
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: install
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**Install Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: install
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`Package Index Options <Package Index Options>`
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
||||||
|
|
||||||
.. _`pip install Examples`:
|
|
||||||
|
|
||||||
Examples
|
|
||||||
********
|
|
||||||
|
|
||||||
1) Install `SomePackage` and it's dependencies from `PyPI`_ using :ref:`Requirement Specifiers`
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install SomePackage # latest version
|
|
||||||
$ pip install SomePackage==1.0.4 # specific version
|
|
||||||
$ pip install 'SomePackage>=1.0.4' # minimum version
|
|
||||||
|
|
||||||
|
|
||||||
2) Install a list of requirements specified in a file. See the :ref:`Cookbook entry on Requirements files <Requirements Files>`.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install -r requirements.txt
|
|
||||||
|
|
||||||
|
|
||||||
3) Upgrade an already installed `SomePackage` to the latest from PyPI.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install --upgrade SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
4) Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install -e . # project in current directory
|
|
||||||
$ pip install -e path/to/project # project in another directory
|
|
||||||
|
|
||||||
|
|
||||||
5) Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support <VCS Support>` and :ref:`Editable Installs <editable-installs>`.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git
|
|
||||||
$ pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial
|
|
||||||
$ pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn
|
|
||||||
$ pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch
|
|
||||||
$ pip install -e git+https://git.repo/some_repo.git@egg=subdir&subdirectory=subdir_path # install a python package from a repo subdirectory
|
|
||||||
|
|
||||||
6) Install a package with `setuptools extras`_.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install SomePackage[PDF]
|
|
||||||
$ pip install SomePackage[PDF]==3.0
|
|
||||||
$ pip install -e .[PDF]==3.0 # editable project in current directory
|
|
||||||
|
|
||||||
|
|
||||||
7) Install a particular source archive file.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install ./downloads/SomePackage-1.0.4.tar.gz
|
|
||||||
$ pip install http://my.package.repo/SomePackage-1.0.4.zip
|
|
||||||
|
|
||||||
|
|
||||||
8) Install from alternative package repositories.
|
|
||||||
|
|
||||||
Install from a different index, and not `PyPI`_::
|
|
||||||
|
|
||||||
$ pip install --index-url http://my.package.repo/simple/ SomePackage
|
|
||||||
|
|
||||||
Search an additional index during install, in addition to `PyPI`_::
|
|
||||||
|
|
||||||
$ pip install --extra-index-url http://my.package.repo/simple SomePackage
|
|
||||||
|
|
||||||
Install from a local flat directory containing archives (and don't scan indexes)::
|
|
||||||
|
|
||||||
$ pip install --no-index --find-links=file:///local/dir/ SomePackage
|
|
||||||
$ pip install --no-index --find-links=/local/dir/ SomePackage
|
|
||||||
$ pip install --no-index --find-links=relative/dir/ SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
9) Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install --pre SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. _PyPI: http://pypi.python.org/pypi
|
|
||||||
.. _setuptools extras: http://packages.python.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
|
|
||||||
|
|
||||||
|
|
||||||
pip uninstall
|
|
||||||
-------------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
.. pip-command-usage:: uninstall
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: uninstall
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**Uninstall Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: uninstall
|
|
||||||
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
||||||
|
|
||||||
Examples
|
|
||||||
********
|
|
||||||
|
|
||||||
1) Uninstall a package.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip uninstall simplejson
|
|
||||||
Uninstalling simplejson:
|
|
||||||
/home/me/env/lib/python2.7/site-packages/simplejson
|
|
||||||
/home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info
|
|
||||||
Proceed (y/n)? y
|
|
||||||
Successfully uninstalled simplejson
|
|
||||||
|
|
||||||
|
|
||||||
.. _`pip freeze`:
|
|
||||||
|
|
||||||
pip freeze
|
|
||||||
-----------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
.. pip-command-usage:: freeze
|
|
||||||
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: freeze
|
|
||||||
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**Freeze Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: freeze
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
||||||
|
|
||||||
Examples
|
|
||||||
********
|
|
||||||
|
|
||||||
1) Generate output suitable for a requirements file.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip freeze
|
|
||||||
Jinja2==2.6
|
|
||||||
Pygments==1.5
|
|
||||||
Sphinx==1.1.3
|
|
||||||
docutils==0.9.1
|
|
||||||
|
|
||||||
|
|
||||||
2) Generate a requirements file and then install from it in another environment.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ env1/bin/pip freeze > requirements.txt
|
|
||||||
$ env2/bin/pip install -r requirements.txt
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
pip list
|
|
||||||
---------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
.. pip-command-usage:: list
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: list
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**List Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: list
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`Package Index Options <Package Index Options>`
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
||||||
|
|
||||||
Examples
|
|
||||||
********
|
|
||||||
|
|
||||||
1) List installed packages.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip list
|
|
||||||
Pygments (1.5)
|
|
||||||
docutils (0.9.1)
|
|
||||||
Sphinx (1.1.2)
|
|
||||||
Jinja2 (2.6)
|
|
||||||
|
|
||||||
2) List outdated packages (excluding editables), and the latest version available
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip list --outdated
|
|
||||||
docutils (Current: 0.9.1 Latest: 0.10)
|
|
||||||
Sphinx (Current: 1.1.2 Latest: 1.1.3)
|
|
||||||
|
|
||||||
pip show
|
|
||||||
--------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
.. pip-command-usage:: show
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: show
|
|
||||||
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**Show Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: show
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
||||||
|
|
||||||
Examples
|
|
||||||
********
|
|
||||||
|
|
||||||
1. Show information about a package:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip show sphinx
|
|
||||||
---
|
|
||||||
Name: Sphinx
|
|
||||||
Version: 1.1.3
|
|
||||||
Location: /my/env/lib/pythonx.x/site-packages
|
|
||||||
Requires: Pygments, Jinja2, docutils
|
|
||||||
|
|
||||||
pip search
|
|
||||||
----------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
.. pip-command-usage:: search
|
|
||||||
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: search
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**Search Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: search
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
||||||
Examples
|
|
||||||
********
|
|
||||||
|
|
||||||
1. Search for "peppercorn"
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip search peppercorn
|
|
||||||
pepperedform - Helpers for using peppercorn with formprocess.
|
|
||||||
peppercorn - A library for converting a token stream into [...]
|
|
||||||
|
|
||||||
.. _`pip wheel`:
|
|
||||||
|
|
||||||
pip wheel
|
|
||||||
---------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
.. pip-command-usage:: wheel
|
|
||||||
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: wheel
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
Currently, when ``pip wheel`` finds a wheel for one of your requirements
|
|
||||||
already on PyPI, it does not rebuild, and it does not place the file in your
|
|
||||||
wheelhouse dir. There is an issue open to change this
|
|
||||||
(https://github.com/pypa/pip/issues/1310)
|
|
||||||
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**Wheel Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: wheel
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`Package Index Options <Package Index Options>`
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
||||||
Examples
|
|
||||||
********
|
|
||||||
|
|
||||||
1. Build wheels for a requirement (and all its dependencies), and then install
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage
|
|
||||||
$ pip install --no-index --find-links=/tmp/wheelhouse SomePackage
|
|
||||||
|
|
||||||
|
|
||||||
pip zip
|
|
||||||
-------
|
|
||||||
|
|
||||||
Usage
|
|
||||||
*****
|
|
||||||
|
|
||||||
.. pip-command-usage:: zip
|
|
||||||
|
|
||||||
Description
|
|
||||||
***********
|
|
||||||
|
|
||||||
.. pip-command-description:: zip
|
|
||||||
|
|
||||||
Options
|
|
||||||
*******
|
|
||||||
|
|
||||||
**Zip Options:**
|
|
||||||
|
|
||||||
.. pip-command-options:: zip
|
|
||||||
|
|
||||||
**Other Options:**
|
|
||||||
|
|
||||||
* :ref:`General Options <General Options>`
|
|
||||||
|
|
516
docs/user_guide.rst
Normal file
516
docs/user_guide.rst
Normal file
|
@ -0,0 +1,516 @@
|
||||||
|
==========
|
||||||
|
User Guide
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Installing Packages
|
||||||
|
*******************
|
||||||
|
|
||||||
|
pip supports installing from `PyPI`_, version control, local projects, and
|
||||||
|
directly from distribution files.
|
||||||
|
|
||||||
|
|
||||||
|
The most common scenario is to install from `PyPI`_ using :ref:`Requirement
|
||||||
|
Specifiers`
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip install SomePackage # latest version
|
||||||
|
$ pip install SomePackage==1.0.4 # specific version
|
||||||
|
$ pip install 'SomePackage>=1.0.4' # minimum version
|
||||||
|
|
||||||
|
|
||||||
|
For more information and examples, see the :ref:`pip install` reference.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`Requirements Files`:
|
||||||
|
|
||||||
|
Requirements Files
|
||||||
|
******************
|
||||||
|
|
||||||
|
"Requirements files" are files containing a list of items to be
|
||||||
|
installed using :ref:`pip install` like so:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
|
||||||
|
Details on the format of the files are here: :ref:`Requirements File Format`.
|
||||||
|
|
||||||
|
Logically, a Requirements file is just a list of :ref:`pip install` arguments
|
||||||
|
placed in a file.
|
||||||
|
|
||||||
|
In practice, there are 4 common uses of Requirements files:
|
||||||
|
|
||||||
|
1. Requirements files are used to hold the result from :ref:`pip freeze` for the
|
||||||
|
purpose of achieving :ref:`repeatable installations <Repeatability>`. In
|
||||||
|
this case, your requirement file contains a pinned version of everything that
|
||||||
|
was installed when `pip freeze` was run.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pip freeze > requirements.txt
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
2. Requirements files are used to force pip to properly resolve dependencies.
|
||||||
|
As it is now, pip `doesn't have true dependency resolution
|
||||||
|
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses the first
|
||||||
|
specification it finds for a project. E.g if `pkg1` requires `pkg3>=1.0` and
|
||||||
|
`pkg2` requires `pkg3>=1.0,<=2.0`, and if `pkg1` is resolved first, pip will
|
||||||
|
only use `pkg3>=1.0`, and could easily end up installing a version of `pkg3`
|
||||||
|
that conflicts with the needs of `pkg2`. To solve this problem, you can
|
||||||
|
place `pkg3>=1.0,<=2.0` (i.e. the correct specification) into your
|
||||||
|
requirements file directly along with the other top level requirements. Like
|
||||||
|
so:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pkg1
|
||||||
|
pkg2
|
||||||
|
pkg3>=1.0,<=2.0
|
||||||
|
|
||||||
|
|
||||||
|
3. Requirements files are used to force pip to install an alternate version of a
|
||||||
|
sub-dependency. For example, suppose `ProjectA` in your requirements file
|
||||||
|
requires `ProjectB`, but the latest version (v1.3) has a bug, you can force
|
||||||
|
pip to accept earlier versions like so:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
ProjectA
|
||||||
|
ProjectB<1.3
|
||||||
|
|
||||||
|
4. Requirements files are used to override a dependency with a local patch that
|
||||||
|
lives in version control. For example, suppose a dependency,
|
||||||
|
`SomeDependency` from PyPI has a bug, and you can't wait for an upstream fix.
|
||||||
|
You could clone/copy the src, make the fix, and place it in vcs with the tag
|
||||||
|
`sometag`. You'd reference it in your requirements file with a line like so:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
git+https://myvcs.com/some_dependency@sometag#egg=SomeDependency
|
||||||
|
|
||||||
|
If `SomeDependency` was previously a top-level requirement in your
|
||||||
|
requirements file, then **replace** that line with the new line. If
|
||||||
|
`SomeDependency` is a sub-dependency, then **add** the new line.
|
||||||
|
|
||||||
|
|
||||||
|
It's important to be clear that pip determines package dependencies using
|
||||||
|
`install_requires metadata
|
||||||
|
<http://pythonhosted.org/setuptools/setuptools.html#declaring-dependencies>`_,
|
||||||
|
not by discovering `requirements.txt` files embedded in projects.
|
||||||
|
|
||||||
|
See also:
|
||||||
|
|
||||||
|
* :ref:`Requirements File Format`
|
||||||
|
* :ref:`pip freeze`
|
||||||
|
* `"setup.py vs requirements.txt" (an article by Donald Stufft)
|
||||||
|
<https://caremad.io/blog/setup-vs-requirement/>`_
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _`Installing from Wheels`:
|
||||||
|
|
||||||
|
Installing from Wheels
|
||||||
|
**********************
|
||||||
|
|
||||||
|
"Wheel" is a built, archive format that can greatly speed installation compared
|
||||||
|
to building and installing from source archives. For more information, see the
|
||||||
|
`Wheel docs <http://wheel.readthedocs.org>`_ ,
|
||||||
|
`PEP427 <http://www.python.org/dev/peps/pep-0427>`_, and
|
||||||
|
`PEP425 <http://www.python.org/dev/peps/pep-0425>`_
|
||||||
|
|
||||||
|
Pip prefers Wheels where they are available. To disable this, use the
|
||||||
|
:ref:`--no-use-wheel <install_--no-use-wheel>` flag for :ref:`pip install`.
|
||||||
|
|
||||||
|
If no satisfactory wheels are found, pip will default to finding source archives.
|
||||||
|
|
||||||
|
|
||||||
|
To install directly from a wheel archive:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pip install SomePackage-1.0-py2.py3-none-any.whl
|
||||||
|
|
||||||
|
|
||||||
|
For the cases where wheels are not available, pip offers :ref:`pip wheel` as a
|
||||||
|
convenience, to build wheels for all your requirements and dependencies.
|
||||||
|
|
||||||
|
:ref:`pip wheel` requires the `wheel package
|
||||||
|
<https://pypi.python.org/pypi/wheel>`_ to be installed, which provides the
|
||||||
|
"bdist_wheel" setuptools extension that it uses.
|
||||||
|
|
||||||
|
To build wheels for your requirements and all their dependencies to a local directory:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pip install wheel
|
||||||
|
pip wheel --wheel-dir=/local/wheels -r requirements.txt
|
||||||
|
|
||||||
|
|
||||||
|
And *then* to install those requirements just using your local directory of wheels (and not from PyPI):
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pip install --no-index --find-links=/local/wheels -r requirements.txt
|
||||||
|
|
||||||
|
|
||||||
|
Uninstalling Packages
|
||||||
|
*********************
|
||||||
|
|
||||||
|
pip is able to uninstall most packages like so:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip uninstall SomePackage
|
||||||
|
|
||||||
|
pip also performs an automatic uninstall of an old version of a package
|
||||||
|
before upgrading to a newer version.
|
||||||
|
|
||||||
|
For more information and examples, see the :ref:`pip uninstall` reference.
|
||||||
|
|
||||||
|
|
||||||
|
Listing Packages
|
||||||
|
****************
|
||||||
|
|
||||||
|
To list installed packages:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip list
|
||||||
|
Pygments (1.5)
|
||||||
|
docutils (0.9.1)
|
||||||
|
Sphinx (1.1.2)
|
||||||
|
Jinja2 (2.6)
|
||||||
|
|
||||||
|
To list outdated packages, and show the latest version available:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip list --outdated
|
||||||
|
docutils (Current: 0.9.1 Latest: 0.10)
|
||||||
|
Sphinx (Current: 1.1.2 Latest: 1.1.3)
|
||||||
|
|
||||||
|
|
||||||
|
To show details about an installed package:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ pip show sphinx
|
||||||
|
---
|
||||||
|
Name: Sphinx
|
||||||
|
Version: 1.1.3
|
||||||
|
Location: /my/env/lib/pythonx.x/site-packages
|
||||||
|
Requires: Pygments, Jinja2, docutils
|
||||||
|
|
||||||
|
|
||||||
|
For more information and examples, see the :ref:`pip list` and :ref:`pip show`
|
||||||
|
reference pages.
|
||||||
|
|
||||||
|
|
||||||
|
Searching for Packages
|
||||||
|
**********************
|
||||||
|
|
||||||
|
pip can search `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.
|
||||||
|
|
||||||
|
For more information and examples, see the :ref:`pip search` reference.
|
||||||
|
|
||||||
|
.. _`Configuration`:
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
*************
|
||||||
|
|
||||||
|
.. _config-file:
|
||||||
|
|
||||||
|
Config file
|
||||||
|
------------
|
||||||
|
|
||||||
|
pip allows you to set all command line option defaults in a standard ini
|
||||||
|
style config file.
|
||||||
|
|
||||||
|
The names and locations of the configuration files vary slightly across
|
||||||
|
platforms.
|
||||||
|
|
||||||
|
* On Unix and Mac OS X the configuration file is: :file:`$HOME/.pip/pip.conf`
|
||||||
|
* On Windows, the configuration file is: :file:`%HOME%\\pip\\pip.ini`
|
||||||
|
|
||||||
|
You can set a custom path location for the config file using the environment variable ``PIP_CONFIG_FILE``.
|
||||||
|
|
||||||
|
In a virtual environment, an additional config file will be read from the base
|
||||||
|
directory of the virtualenv (``sys.prefix`` as reported by Python). The base
|
||||||
|
name of the file is the same as the user configuration file (:file:`pip.conf`
|
||||||
|
on Unix and OSX, :file:`pip.ini` on Windows). Values in the virtualenv-specific
|
||||||
|
configuration file take precedence over those in the user's configuration file
|
||||||
|
(whether from the user home or specified via ``PIP_CONFIG_FILE``).
|
||||||
|
|
||||||
|
The names of the settings are derived from the long command line option, e.g.
|
||||||
|
if you want to use a different package index (``--index-url``) and set the
|
||||||
|
HTTP timeout (``--default-timeout``) to 60 seconds your config file would
|
||||||
|
look like this:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[global]
|
||||||
|
timeout = 60
|
||||||
|
index-url = http://download.zope.org/ppix
|
||||||
|
|
||||||
|
Each subcommand can be configured optionally in its own section so that every
|
||||||
|
global setting with the same name will be overridden; e.g. decreasing the
|
||||||
|
``timeout`` to ``10`` seconds when running the `freeze`
|
||||||
|
(`Freezing Requirements <./#freezing-requirements>`_) command and using
|
||||||
|
``60`` seconds for all other commands is possible with:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[global]
|
||||||
|
timeout = 60
|
||||||
|
|
||||||
|
[freeze]
|
||||||
|
timeout = 10
|
||||||
|
|
||||||
|
|
||||||
|
Boolean options like ``--ignore-installed`` or ``--no-dependencies`` can be
|
||||||
|
set like this:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[install]
|
||||||
|
ignore-installed = true
|
||||||
|
no-dependencies = yes
|
||||||
|
|
||||||
|
Appending options like ``--find-links`` can be written on multiple lines:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[global]
|
||||||
|
find-links =
|
||||||
|
http://download.example.com
|
||||||
|
|
||||||
|
[install]
|
||||||
|
find-links =
|
||||||
|
http://mirror1.example.com
|
||||||
|
http://mirror2.example.com
|
||||||
|
|
||||||
|
|
||||||
|
Environment Variables
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
pip's command line options can be set with environment variables using the
|
||||||
|
format ``PIP_<UPPER_LONG_NAME>`` . Dashes (``-``) have to be replaced with
|
||||||
|
underscores (``_``).
|
||||||
|
|
||||||
|
For example, to set the default timeout::
|
||||||
|
|
||||||
|
export PIP_DEFAULT_TIMEOUT=60
|
||||||
|
|
||||||
|
This is the same as passing the option to pip directly::
|
||||||
|
|
||||||
|
pip --default-timeout=60 [...]
|
||||||
|
|
||||||
|
To set options that can be set multiple times on the command line, just add
|
||||||
|
spaces in between values. For example::
|
||||||
|
|
||||||
|
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
|
||||||
|
|
||||||
|
is the same as calling::
|
||||||
|
|
||||||
|
pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
|
||||||
|
|
||||||
|
|
||||||
|
Config Precedence
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Command line options have precedence over environment variables, which have precedence over the config file.
|
||||||
|
|
||||||
|
Within the config file, command specific sections have precedence over the global section.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- ``--host=foo`` overrides ``PIP_HOST=foo``
|
||||||
|
- ``PIP_HOST=foo`` overrides a config file with ``[global] host = foo``
|
||||||
|
- A command specific section in the config file ``[<command>] host = bar``
|
||||||
|
overrides the option with same name in the ``[global]`` config file section
|
||||||
|
|
||||||
|
|
||||||
|
Command Completion
|
||||||
|
------------------
|
||||||
|
|
||||||
|
pip comes with support for command line completion in bash and zsh.
|
||||||
|
|
||||||
|
To setup for bash::
|
||||||
|
|
||||||
|
$ pip completion --bash >> ~/.profile
|
||||||
|
|
||||||
|
To setup for zsh::
|
||||||
|
|
||||||
|
$ pip completion --zsh >> ~/.zprofile
|
||||||
|
|
||||||
|
Alternatively, you can use the result of the ``completion`` command
|
||||||
|
directly with the eval function of you shell, e.g. by adding the following to your startup file::
|
||||||
|
|
||||||
|
eval "`pip completion --bash`"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _`Fast & Local Installs`:
|
||||||
|
|
||||||
|
Fast & Local Installs
|
||||||
|
*********************
|
||||||
|
|
||||||
|
Often, you will want a fast install from local archives, without probing PyPI.
|
||||||
|
|
||||||
|
First, download the archives that fulfill your requirements::
|
||||||
|
|
||||||
|
$ pip install --download <DIR> -r requirements.txt
|
||||||
|
|
||||||
|
Then, install using :ref:`--find-links <--find-links>` and :ref:`--no-index <--no-index>`::
|
||||||
|
|
||||||
|
$ pip install --no-index --find-links=[file://]<DIR> -r requirements.txt
|
||||||
|
|
||||||
|
|
||||||
|
Non-recursive upgrades
|
||||||
|
************************
|
||||||
|
|
||||||
|
``pip install --upgrade`` is currently written to perform a recursive upgrade.
|
||||||
|
|
||||||
|
E.g. supposing:
|
||||||
|
|
||||||
|
* `SomePackage-1.0` requires `AnotherPackage>=1.0`
|
||||||
|
* `SomePackage-2.0` requires `AnotherPackage>=1.0` and `OneMorePoject==1.0`
|
||||||
|
* `SomePackage-1.0` and `AnotherPackage-1.0` are currently installed
|
||||||
|
* `SomePackage-2.0` and `AnotherPackage-2.0` are the latest versions available on PyPI.
|
||||||
|
|
||||||
|
Running ``pip install --upgrade SomePackage`` would upgrade `SomePackage` *and* `AnotherPackage`
|
||||||
|
despite `AnotherPackage` already being satisifed.
|
||||||
|
|
||||||
|
If you would like to perform a non-recursive upgrade perform these 2 steps::
|
||||||
|
|
||||||
|
pip install --upgrade --no-deps SomePackage
|
||||||
|
pip install SomePackage
|
||||||
|
|
||||||
|
The first line will upgrade `SomePackage`, but not dependencies like `AnotherPackage`. The 2nd line will fill in new dependencies like `OneMorePackage`.
|
||||||
|
|
||||||
|
|
||||||
|
User Installs
|
||||||
|
*************
|
||||||
|
|
||||||
|
With Python 2.6 came the `"user scheme" for installation
|
||||||
|
<http://docs.python.org/install/index.html#alternate-installation-the-user-scheme>`_,
|
||||||
|
which means that all Python distributions support an alternative install
|
||||||
|
location that is specific to a user. The default location for each OS is
|
||||||
|
explained in the python documentation for the `site.USER_BASE
|
||||||
|
<http://docs.python.org/library/site.html#site.USER_BASE>`_ variable. This mode
|
||||||
|
of installation can be turned on by specifying the :ref:`--user
|
||||||
|
<install_--user>` option to ``pip install``.
|
||||||
|
|
||||||
|
Moreover, the "user scheme" can be customized by setting the
|
||||||
|
``PYTHONUSERBASE`` environment variable, which updates the value of ``site.USER_BASE``.
|
||||||
|
|
||||||
|
To install "SomePackage" into an environment with site.USER_BASE customized to '/myappenv', do the following::
|
||||||
|
|
||||||
|
export PYTHONUSERBASE=/myappenv
|
||||||
|
pip install --user SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
``pip install --user`` follows four rules:
|
||||||
|
|
||||||
|
#. When globally installed packages are on the python path, and they *conflict*
|
||||||
|
with the installation requirements, they are ignored, and *not*
|
||||||
|
uninstalled.
|
||||||
|
#. When globally installed packages are on the python path, and they *satisfy*
|
||||||
|
the installation requirements, pip does nothing, and reports that
|
||||||
|
requirement is satisfied (similar to how global packages can satisfy
|
||||||
|
requirements when installing packages in a ``--system-site-packages``
|
||||||
|
virtualenv).
|
||||||
|
#. pip will not perform a ``--user`` install in a ``--no-site-packages``
|
||||||
|
virtualenv (i.e. the default kind of virtualenv), due to the user site not
|
||||||
|
being on the python path. The installation would be pointless.
|
||||||
|
#. In a ``--system-site-packages`` virtualenv, pip will not install a package
|
||||||
|
that conflicts with a package in the virtualenv site-packages. The --user
|
||||||
|
installation would lack sys.path precedence and be pointless.
|
||||||
|
|
||||||
|
|
||||||
|
To make the rules clearer, here are some examples:
|
||||||
|
|
||||||
|
|
||||||
|
From within a ``--no-site-packages`` virtualenv (i.e. the default kind)::
|
||||||
|
|
||||||
|
$ pip install --user SomePackage
|
||||||
|
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
|
||||||
|
|
||||||
|
|
||||||
|
From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3`` is already installed in the virtualenv::
|
||||||
|
|
||||||
|
$ pip install --user SomePackage==0.4
|
||||||
|
Will not install to the user site because it will lack sys.path precedence
|
||||||
|
|
||||||
|
|
||||||
|
From within a real python, where ``SomePackage`` is *not* installed globally::
|
||||||
|
|
||||||
|
$ pip install --user SomePackage
|
||||||
|
[...]
|
||||||
|
Successfully installed SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
From within a real python, where ``SomePackage`` *is* installed globally, but is *not* the latest version::
|
||||||
|
|
||||||
|
$ pip install --user SomePackage
|
||||||
|
[...]
|
||||||
|
Requirement already satisfied (use --upgrade to upgrade)
|
||||||
|
|
||||||
|
$ pip install --user --upgrade SomePackage
|
||||||
|
[...]
|
||||||
|
Successfully installed SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
From within a real python, where ``SomePackage`` *is* installed globally, and is the latest version::
|
||||||
|
|
||||||
|
$ pip install --user SomePackage
|
||||||
|
[...]
|
||||||
|
Requirement already satisfied (use --upgrade to upgrade)
|
||||||
|
|
||||||
|
$ pip install --user --upgrade SomePackage
|
||||||
|
[...]
|
||||||
|
Requirement already up-to-date: SomePackage
|
||||||
|
|
||||||
|
# force the install
|
||||||
|
$ pip install --user --ignore-installed SomePackage
|
||||||
|
[...]
|
||||||
|
Successfully installed SomePackage
|
||||||
|
|
||||||
|
|
||||||
|
.. _`Repeatability`:
|
||||||
|
|
||||||
|
Ensuring Repeatability
|
||||||
|
**********************
|
||||||
|
|
||||||
|
Three things are required to fully guarantee a repeatable installation using requirements files.
|
||||||
|
|
||||||
|
1. The requirements file was generated by ``pip freeze`` or you're sure it only
|
||||||
|
contains requirements that specify a specific version.
|
||||||
|
|
||||||
|
2. The installation is performed using :ref:`--no-deps <install_--no-deps>`.
|
||||||
|
This guarantees that only what is explicitly listed in the requirements file is
|
||||||
|
installed.
|
||||||
|
|
||||||
|
3. The installation is performed against an index or find-links location that is
|
||||||
|
guaranteed to *not* allow archives to be changed and updated without a
|
||||||
|
version increase. Unfortunately, this is *not* true on PyPI. It is possible
|
||||||
|
for the same pypi distribution to have a different hash over time. Project
|
||||||
|
authors are allowed to delete a distribution, and then upload a new one with
|
||||||
|
the same name and version, but a different hash. See `Issue #1175
|
||||||
|
<https://github.com/pypa/pip/issues/1175>`_ for plans to add hash
|
||||||
|
confirmation to pip, or a new "lock file" notion, but for now, know that the `peep
|
||||||
|
project <https://pypi.python.org/pypi/peep>`_ offers this feature on top of pip
|
||||||
|
using requirements file comments.
|
||||||
|
|
||||||
|
|
||||||
|
.. _PyPI: http://pypi.python.org/pypi/
|
|
@ -22,9 +22,6 @@ class InstallCommand(Command):
|
||||||
|
|
||||||
pip also supports installing from "requirements files", which provide
|
pip also supports installing from "requirements files", which provide
|
||||||
an easy way to specify a whole environment to be installed.
|
an easy way to specify a whole environment to be installed.
|
||||||
|
|
||||||
See http://www.pip-installer.org for details on VCS url formats and
|
|
||||||
requirements files.
|
|
||||||
"""
|
"""
|
||||||
name = 'install'
|
name = 'install'
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue