mirror of https://github.com/pypa/pip
pip docs refactor
This commit is contained in:
Marcus Smith
parent
ffcd44c716
commit
96bfe8b0f9
178
CHANGES.txt
178
CHANGES.txt
|
|
@ -1,8 +1,7 @@
|
|||
Changelog
|
||||
=========
|
||||
|
||||
1.6.0.dev1 (unreleased)
|
||||
-----------------------
|
||||
|
||||
**1.6.0.dev1 (unreleased)**
|
||||
|
||||
|
||||
* Fixed #1112. Couldn't download directly from wheel paths/urls, and when wheel
|
||||
downloads did occur using requirement specifiers, dependencies weren't
|
||||
|
|
@ -15,8 +14,8 @@ Changelog
|
|||
``--find-links`` (PR #1524)
|
||||
|
||||
|
||||
1.5.2 (2014-01-26)
|
||||
------------------
|
||||
**1.5.2 (2014-01-26)**
|
||||
|
||||
|
||||
* Upgraded the vendored ``pkg_resources`` and ``_markerlib`` to setuptools 2.1.
|
||||
|
||||
|
|
@ -27,8 +26,8 @@ Changelog
|
|||
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
|
||||
installing distributions from src (i.e. not from wheel). (Pull #1434).
|
||||
|
|
@ -46,9 +45,8 @@ Changelog
|
|||
#1457)
|
||||
|
||||
|
||||
**1.5 (2014-01-01)**
|
||||
|
||||
1.5 (2014-01-01)
|
||||
----------------
|
||||
|
||||
* **BACKWARD INCOMPATIBLE** pip no longer supports the ``--use-mirrors``,
|
||||
``-M``, and ``--mirrors`` flags. The mirroring support has been removed. In
|
||||
|
|
@ -124,11 +122,9 @@ Changelog
|
|||
(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
|
||||
fingerprint: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
|
||||
* Fixed issues with installing from pybundle files (Pull #1116).
|
||||
|
|
@ -139,8 +135,8 @@ Changelog
|
|||
* 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,
|
||||
and offers a new ``--pre`` option to also find pre-release and development
|
||||
|
|
@ -188,14 +184,16 @@ Changelog
|
|||
|
||||
* 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
|
||||
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.
|
||||
Thanks James Cleveland, Giovanni Bajo, Marcus Smith and many others (Pull #791, CVE-2013-1629).
|
||||
|
|
@ -251,15 +249,17 @@ Changelog
|
|||
like the same option in distutils but also plays nice with pip's egg-info.
|
||||
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
|
||||
not finding any files to uninstall in the current environment. Thanks for
|
||||
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
|
||||
now Python 2.5.
|
||||
|
|
@ -327,8 +327,9 @@ Changelog
|
|||
|
||||
* 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
|
||||
then fails. Thanks Marc Abramowitz.
|
||||
|
|
@ -387,8 +388,8 @@ Changelog
|
|||
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 issue #295 - Reinstall a package when using the ``install -I`` option
|
||||
|
|
@ -397,8 +398,9 @@ Changelog
|
|||
* Fixed issue #314 - Correctly handle exceptions on Python3.
|
||||
* 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.
|
||||
* Fixed issue #274 - `find_command` should not raise AttributeError
|
||||
|
|
@ -408,8 +410,9 @@ Changelog
|
|||
* Fixed issue #44 - multiple CLI searches.
|
||||
* 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
|
||||
Hightower, and Alex Gronholm, among others.
|
||||
|
|
@ -436,8 +439,9 @@ Changelog
|
|||
Make sure you have `distribute <http://pypi.python.org/pypi/distribute>`_
|
||||
installed before using the installer!
|
||||
|
||||
0.8.3
|
||||
-----
|
||||
|
||||
**0.8.3**
|
||||
|
||||
|
||||
* Moved main repository to Github: https://github.com/pypa/pip
|
||||
|
||||
|
|
@ -459,8 +463,9 @@ Changelog
|
|||
|
||||
* Fixed bug in version string parsing related to the suffix "-dev".
|
||||
|
||||
0.8.2
|
||||
-----
|
||||
|
||||
**0.8.2**
|
||||
|
||||
|
||||
* Avoid redundant unpacking of bundles (from pwaller)
|
||||
|
||||
|
|
@ -476,8 +481,9 @@ Changelog
|
|||
|
||||
* 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
|
||||
Ronny Pfannschmidt.
|
||||
|
|
@ -496,9 +502,8 @@ Changelog
|
|||
Thanks Ronny Pfannschmidt and Wil Tan.
|
||||
|
||||
|
||||
**0.8**
|
||||
|
||||
0.8
|
||||
---
|
||||
|
||||
* Track which ``build/`` directories pip creates, never remove directories
|
||||
it doesn't create. From Hugo Lopes Tavares.
|
||||
|
|
@ -524,14 +529,16 @@ Changelog
|
|||
|
||||
* 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
|
||||
pip is installed as a zip file.
|
||||
|
||||
0.7.1
|
||||
-----
|
||||
|
||||
**0.7.1**
|
||||
|
||||
|
||||
* Fixed opening of logfile with no directory name. Thanks Alexandre Conrad.
|
||||
|
||||
|
|
@ -540,8 +547,9 @@ Changelog
|
|||
|
||||
* Tests now require at least ScriptTest 1.0.3.
|
||||
|
||||
0.7
|
||||
---
|
||||
|
||||
**0.7**
|
||||
|
||||
|
||||
* Fixed uninstallation on Windows
|
||||
* Added ``pip search`` command.
|
||||
|
|
@ -582,21 +590,24 @@ Changelog
|
|||
--extra-index-url.
|
||||
* 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
|
||||
package
|
||||
|
||||
0.6.2
|
||||
-----
|
||||
|
||||
**0.6.2**
|
||||
|
||||
|
||||
* Fixed uninstall when /tmp is on a different filesystem.
|
||||
|
||||
* Fixed uninstallation of distributions with namespace packages.
|
||||
|
||||
0.6.1
|
||||
-----
|
||||
|
||||
**0.6.1**
|
||||
|
||||
|
||||
* Added support for the ``https`` and ``http-static`` schemes to the
|
||||
Mercurial and ``ftp`` scheme to the Bazaar backend.
|
||||
|
|
@ -609,8 +620,9 @@ Changelog
|
|||
* Fixed issue with ``pip bundle`` and local files (which weren't being
|
||||
copied into the bundle), from Whit Morriss.
|
||||
|
||||
0.6
|
||||
---
|
||||
|
||||
**0.6**
|
||||
|
||||
|
||||
* Add ``pip uninstall`` and uninstall-before upgrade (from Carl
|
||||
Meyer).
|
||||
|
|
@ -640,13 +652,15 @@ Changelog
|
|||
|
||||
* Creates download cache directory if not existing.
|
||||
|
||||
0.5.1
|
||||
-----
|
||||
|
||||
**0.5.1**
|
||||
|
||||
|
||||
* 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``)
|
||||
with the environmental variable ``$PIP_LOG_FILE``.
|
||||
|
|
@ -698,8 +712,9 @@ Changelog
|
|||
* Fixed handling of attempt to checkout editable install to a
|
||||
non-empty, non-repo directory.
|
||||
|
||||
0.4
|
||||
---
|
||||
|
||||
**0.4**
|
||||
|
||||
|
||||
* Make ``-e`` work better with local hg repositories
|
||||
|
||||
|
|
@ -727,8 +742,9 @@ Changelog
|
|||
|
||||
* Fixed support for Subversion 1.6.
|
||||
|
||||
0.3.1
|
||||
-----
|
||||
|
||||
**0.3.1**
|
||||
|
||||
|
||||
* Improved virtualenv restart and various path/cleanup problems on win32.
|
||||
|
||||
|
|
@ -740,8 +756,9 @@ Changelog
|
|||
|
||||
* Improve ``pip -h``
|
||||
|
||||
0.3
|
||||
---
|
||||
|
||||
**0.3**
|
||||
|
||||
|
||||
* Added support for editable packages created from Git, Mercurial and Bazaar
|
||||
repositories and ability to freeze them. Refactored support for version
|
||||
|
|
@ -777,8 +794,9 @@ Changelog
|
|||
|
||||
* Add ``--simulate`` option to ``pip zip``.
|
||||
|
||||
0.2.1
|
||||
-----
|
||||
|
||||
**0.2.1**
|
||||
|
||||
|
||||
* Fixed small problem that prevented using ``pip.py`` without actually
|
||||
installing pip.
|
||||
|
|
@ -797,8 +815,9 @@ Changelog
|
|||
|
||||
* Turn some tar file errors into warnings.
|
||||
|
||||
0.2
|
||||
---
|
||||
|
||||
**0.2**
|
||||
|
||||
|
||||
* Renamed to ``pip``, and to install you now do ``pip install
|
||||
PACKAGE``
|
||||
|
|
@ -811,8 +830,9 @@ Changelog
|
|||
creating a bundle using unnamed packages (like just an svn
|
||||
repository without ``#egg=Package``).
|
||||
|
||||
0.1.4
|
||||
-----
|
||||
|
||||
**0.1.4**
|
||||
|
||||
|
||||
* Added an option ``--install-option`` to pass options to pass
|
||||
arguments to ``setup.py install``
|
||||
|
|
@ -838,16 +858,18 @@ Changelog
|
|||
is still required, but just some downloads will be avoided when
|
||||
using this.
|
||||
|
||||
0.1.3
|
||||
-----
|
||||
|
||||
**0.1.3**
|
||||
|
||||
|
||||
* Always use ``svn checkout`` (not ``export``) so that
|
||||
``tag_svn_revision`` settings give the revision of the package.
|
||||
|
||||
* 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
|
||||
seeking packages.
|
||||
|
|
@ -860,8 +882,9 @@ Changelog
|
|||
|
||||
* Fix ``dependency_links`` for finding packages.
|
||||
|
||||
0.1.1
|
||||
-----
|
||||
|
||||
**0.1.1**
|
||||
|
||||
|
||||
* Fixed a NameError exception when running pip outside of a
|
||||
virtualenv environment.
|
||||
|
|
@ -871,7 +894,8 @@ Changelog
|
|||
* Fixed use of ``hashlib.md5`` on python2.5+ (also from Prabhu
|
||||
Ramachandran)
|
||||
|
||||
0.1
|
||||
---
|
||||
|
||||
**0.1**
|
||||
|
||||
|
||||
* Initial release
|
||||
|
|
|
|||
|
|
@ -7,4 +7,5 @@ Project Info
|
|||
* Bug Tracking: https://github.com/pypa/pip/issues
|
||||
* Mailing list: http://groups.google.com/group/python-virtualenv
|
||||
* Docs: http://www.pip-installer.org/
|
||||
* IRC: #pip on Freenode.
|
||||
* User IRC: #pip on Freenode.
|
||||
* Dev IRC: #pypa on Freenode.
|
||||
|
|
|
|||
|
|
@ -1,133 +1,7 @@
|
|||
.. _`Configuration`:
|
||||
:orphan:
|
||||
|
||||
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 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`"
|
||||
This content is now covered in the :doc:`User Guide <user_guide>`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,444 +1,7 @@
|
|||
:orphan:
|
||||
|
||||
============
|
||||
Cookbook
|
||||
============
|
||||
|
||||
.. _`Requirements Files`:
|
||||
|
||||
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
|
||||
|
||||
|
||||
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
|
||||
This content is now covered in the :doc:`User Guide <user_guide>`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
===
|
||||
|
||||
A tool for installing and managing Python packages.
|
||||
|
||||
`User list <http://groups.google.com/group/python-virtualenv>`_ |
|
||||
`Dev list <http://groups.google.com/group/pypa-dev>`_ |
|
||||
`Issues <https://github.com/pypa/pip/issues>`_ |
|
||||
`Github <https://github.com/pypa/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::
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
installing
|
||||
usage
|
||||
cookbook
|
||||
logic
|
||||
configuration
|
||||
other-tools
|
||||
user_guide
|
||||
reference/index
|
||||
development
|
||||
news
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -29,11 +29,10 @@ Then run the following (which may require administrator access):
|
|||
|
||||
$ 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
|
||||
`get-pip.py`. Additionally, if `setuptools`_ (or `distribute`_) is not
|
||||
already installed, `get-pip.py` will install `setuptools`_ for you.
|
||||
To upgrade an existing `setuptools`_ (or `distribute`_), run ``pip install -U setuptools`` [3]_
|
||||
|
||||
|
||||
Using Package Managers
|
||||
|
|
@ -56,7 +55,14 @@ On Fedora::
|
|||
tool like `curl` that verifies SSL certificates when downloading from
|
||||
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
|
||||
.. _distribute: https://pypi.python.org/pypi/distribute
|
||||
|
||||
|
||||
|
|
|
|||
341
docs/logic.rst
341
docs/logic.rst
|
|
@ -1,345 +1,8 @@
|
|||
.. _`pip logic`:
|
||||
:orphan:
|
||||
|
||||
================
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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])
|
||||
else:
|
||||
bookmark_line = ".. _`%s`:" % option._long_opts[0]
|
||||
line = "``"
|
||||
line = ".. option:: "
|
||||
if option._short_opts:
|
||||
line += option._short_opts[0]
|
||||
if option._short_opts and option._long_opts:
|
||||
|
|
@ -54,7 +54,6 @@ class PipOptions(rst.Directive):
|
|||
if option.takes_value():
|
||||
metavar = option.metavar or option.dest.lower()
|
||||
line += " <%s>" % metavar.lower()
|
||||
line += '``'
|
||||
#fix defaults
|
||||
opt_help = option.help.replace('%default', str(option.default))
|
||||
#fix paths with sys.prefix
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
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
|
||||
|
||||
|
|
@ -50,3 +52,5 @@ Uninstall a package:
|
|||
Proceed (y/n)? y
|
||||
Successfully uninstalled SomePackage
|
||||
|
||||
|
||||
.. _PyPI: http://pypi.python.org/pypi/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,17 @@
|
|||
===============
|
||||
Reference Guide
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
pip
|
||||
pip_install
|
||||
pip_uninstall
|
||||
pip_freeze
|
||||
pip_list
|
||||
pip_show
|
||||
pip_search
|
||||
pip_wheel
|
||||
|
||||
|
||||
|
|
@ -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::
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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)
|
||||
|
|
@ -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`:
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
430
docs/usage.rst
430
docs/usage.rst
|
|
@ -1,431 +1,7 @@
|
|||
:orphan:
|
||||
|
||||
==========
|
||||
Usage
|
||||
==========
|
||||
|
||||
pip
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
|
||||
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>`
|
||||
The "Usage" section is now covered in the :doc:`Reference Guide <reference/index>`
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
@ -24,9 +24,6 @@ class InstallCommand(Command):
|
|||
|
||||
pip also supports installing from "requirements files", which provide
|
||||
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'
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue