From 96bfe8b0f9a8e70c27fff0d136dbbf3bdaa09658 Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Tue, 11 Feb 2014 21:55:43 -0800 Subject: [PATCH] pip docs refactor --- CHANGES.txt | 178 ++++++----- PROJECT.txt | 3 +- docs/configuration.rst | 132 +------- docs/cookbook.rst | 443 +------------------------- docs/distribute_setuptools.rst | 69 +++++ docs/index.rst | 17 +- docs/installing.rst | 18 +- docs/logic.rst | 341 +------------------- docs/news.rst | 6 +- docs/other-tools.rst | 65 ---- docs/pipext.py | 3 +- docs/quickstart.rst | 8 +- docs/reference/index.rst | 17 + docs/reference/pip.rst | 80 +++++ docs/reference/pip_freeze.rst | 46 +++ docs/reference/pip_install.rst | 439 ++++++++++++++++++++++++++ docs/reference/pip_list.rst | 45 +++ docs/reference/pip_search.rst | 36 +++ docs/reference/pip_show.rst | 37 +++ docs/reference/pip_uninstall.rst | 37 +++ docs/reference/pip_wheel.rst | 37 +++ docs/usage.rst | 430 +------------------------- docs/user_guide.rst | 516 +++++++++++++++++++++++++++++++ pip/commands/install.py | 3 - 24 files changed, 1503 insertions(+), 1503 deletions(-) create mode 100644 docs/distribute_setuptools.rst delete mode 100644 docs/other-tools.rst create mode 100644 docs/reference/index.rst create mode 100644 docs/reference/pip.rst create mode 100644 docs/reference/pip_freeze.rst create mode 100644 docs/reference/pip_install.rst create mode 100644 docs/reference/pip_list.rst create mode 100644 docs/reference/pip_search.rst create mode 100644 docs/reference/pip_show.rst create mode 100644 docs/reference/pip_uninstall.rst create mode 100644 docs/reference/pip_wheel.rst create mode 100644 docs/user_guide.rst diff --git a/CHANGES.txt b/CHANGES.txt index 8df64791f..f824e1aad 100644 --- a/CHANGES.txt +++ b/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 `_ 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 diff --git a/PROJECT.txt b/PROJECT.txt index 2cd8b78c1..df0673847 100644 --- a/PROJECT.txt +++ b/PROJECT.txt @@ -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. diff --git a/docs/configuration.rst b/docs/configuration.rst index b1d9faf09..7b31876e0 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -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_`` . 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 ``[] 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 ` diff --git a/docs/cookbook.rst b/docs/cookbook.rst index dabd7328f..83d42a608 100644 --- a/docs/cookbook.rst +++ b/docs/cookbook.rst @@ -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 ` 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 `. - 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 - `_, 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 -`_, 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) -`_ - -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 ` that fulfill your requirements:: - -$ pip install --download -r requirements.txt - -Then, install using :ref:`--find-links <--find-links>` and :ref:`--no-index <--no-index>`:: - -$ pip install --no-index --find-links=[file://] -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 `_ , -`PEP427 `_, and -`PEP425 `_ - -Pip prefers Wheels where they are available, to disable this use the -:ref:`--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 `_ 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 -r requirements.txt - -or, for a specific package:: - -$ pip install --download 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 ``/build``. Otherwise, it's ``/pip-build-`` - -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 `. - 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 - `_ for plans to add hash - confirmation to pip, or a new "lock file" notion, but for now, know that the `peep - project `_ offers this feature on top of pip - using requirements file comments. - -User Installs -************* - -With Python 2.6 came the `"user scheme" for installation -`_, 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 `_ variable. -This mode of installation can be turned on by -specifying the :ref:`--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 `_ -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 ` have an effect. - -The solution is to configure a "system" or "personal" -`Distutils configuration file `_ -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 ` - * *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 ` diff --git a/docs/distribute_setuptools.rst b/docs/distribute_setuptools.rst new file mode 100644 index 000000000..f47dbf8d5 --- /dev/null +++ b/docs/distribute_setuptools.rst @@ -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 ` + * *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 diff --git a/docs/index.rst b/docs/index.rst index acf4b0d03..701d11387 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,26 +1,25 @@ pip === -A tool for installing and managing Python packages. - `User list `_ | `Dev list `_ | -`Issues `_ | `Github `_ | `PyPI `_ | -irc:#pip +User IRC: #pip | +Dev IRC: #pypa +The `PyPA recommended +`_ +tool for installing and managing Python packages. .. toctree:: :maxdepth: 2 quickstart installing - usage - cookbook - logic - configuration - other-tools + user_guide + reference/index development news + diff --git a/docs/installing.rst b/docs/installing.rst index 9a8e739d1..bcb818eba 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -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 `. + .. _setuptools: https://pypi.python.org/pypi/setuptools .. _distribute: https://pypi.python.org/pypi/distribute - - diff --git a/docs/logic.rst b/docs/logic.rst index a56519891..0c27d8ce5 100644 --- a/docs/logic.rst +++ b/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 ` -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:: - - - - [-e] - [-e] - -See the :ref:`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 ` 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 `_ - -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 ` 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 ` (using the :ref:`--editable ` option) or not. - -* For editable installs, the clone location by default is "/src/SomeProject" in virtual environments, and "/src/SomeProject" for global installs. - The :ref:`--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=" 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 `_, -which is documented `here `_ -and `there `_ - -pip offers a set of :ref:`Package Index Options ` for modifying how packages are found. - -See the :ref:`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 ` 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 `, 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" `_ 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/ diff --git a/docs/news.rst b/docs/news.rst index f9820b009..f3291119f 100644 --- a/docs/news.rst +++ b/docs/news.rst @@ -1,5 +1,5 @@ -==== -News -==== +============= +Release Notes +============= .. include:: ../CHANGES.txt diff --git a/docs/other-tools.rst b/docs/other-tools.rst deleted file mode 100644 index e6ad9120e..000000000 --- a/docs/other-tools.rst +++ /dev/null @@ -1,65 +0,0 @@ -=========== -Other tools -=========== - -virtualenv ----------- - -pip is most nutritious when used with `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 `_ 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 - `_ 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 -`_ you should look at -`gp.recipe.pip `_ as an -option to use pip and virtualenv in your buildouts. - diff --git a/docs/pipext.py b/docs/pipext.py index 51d90ff04..f21c6d701 100644 --- a/docs/pipext.py +++ b/docs/pipext.py @@ -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 diff --git a/docs/quickstart.rst b/docs/quickstart.rst index b2d792882..84a9bb83b 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,11 +1,13 @@ Quickstart ========== -Install a package: +First, :doc:`Install pip `. + +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/ diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 000000000..8322f8f1c --- /dev/null +++ b/docs/reference/index.rst @@ -0,0 +1,17 @@ +=============== +Reference Guide +=============== + +.. toctree:: + :maxdepth: 2 + + pip + pip_install + pip_uninstall + pip_freeze + pip_list + pip_show + pip_search + pip_wheel + + diff --git a/docs/reference/pip.rst b/docs/reference/pip.rst new file mode 100644 index 000000000..3becdfd2d --- /dev/null +++ b/docs/reference/pip.rst @@ -0,0 +1,80 @@ + +pip +--- + +.. contents:: + +Usage +***** + +:: + + pip [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:: + diff --git a/docs/reference/pip_freeze.rst b/docs/reference/pip_freeze.rst new file mode 100644 index 000000000..360b69dfc --- /dev/null +++ b/docs/reference/pip_freeze.rst @@ -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 diff --git a/docs/reference/pip_install.rst b/docs/reference/pip_install.rst new file mode 100644 index 000000000..11c596df6 --- /dev/null +++ b/docs/reference/pip_install.rst @@ -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:: + + + + [-e] + [-e] + +See the :ref:`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 `_ + +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 ` 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 ` (using +the :ref:`--editable ` option) or not. + +* For editable installs, the clone location by default is "/src/SomeProject" in virtual environments, and "/src/SomeProject" + for global installs. The :ref:`--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=" 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 `_, +which is documented `here `_ +and `there `_ + +pip offers a number of Package Index Options for modifying how packages are found. + +See the :ref:`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 ` 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 `, 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" +`_ +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 +`_ +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 +`_ 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 `. + + :: + + $ 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 `. + + :: + + $ 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 ` and :ref:`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 diff --git a/docs/reference/pip_list.rst b/docs/reference/pip_list.rst new file mode 100644 index 000000000..feb5f212c --- /dev/null +++ b/docs/reference/pip_list.rst @@ -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) diff --git a/docs/reference/pip_search.rst b/docs/reference/pip_search.rst new file mode 100644 index 000000000..4a2a2dd78 --- /dev/null +++ b/docs/reference/pip_search.rst @@ -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`: diff --git a/docs/reference/pip_show.rst b/docs/reference/pip_show.rst new file mode 100644 index 000000000..0fc505810 --- /dev/null +++ b/docs/reference/pip_show.rst @@ -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 diff --git a/docs/reference/pip_uninstall.rst b/docs/reference/pip_uninstall.rst new file mode 100644 index 000000000..7025981f8 --- /dev/null +++ b/docs/reference/pip_uninstall.rst @@ -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 + diff --git a/docs/reference/pip_wheel.rst b/docs/reference/pip_wheel.rst new file mode 100644 index 000000000..e64f383c1 --- /dev/null +++ b/docs/reference/pip_wheel.rst @@ -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 diff --git a/docs/usage.rst b/docs/usage.rst index 06cc66930..20c2b29ec 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,431 +1,7 @@ +:orphan: + ========== Usage ========== -pip ---- - -Usage -***** - -:: - - pip [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 ` -* :ref:`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 `. - - :: - - $ 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 `. - - :: - - $ 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 ` and :ref:`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 ` - - -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 ` - - -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 ` -* :ref:`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 ` - - -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 ` - -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 ` -* :ref:`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 ` +The "Usage" section is now covered in the :doc:`Reference Guide ` diff --git a/docs/user_guide.rst b/docs/user_guide.rst new file mode 100644 index 000000000..d32a17471 --- /dev/null +++ b/docs/user_guide.rst @@ -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 `. 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 + `_, 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 +`_, +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) + `_ + + + +.. _`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 `_ , +`PEP427 `_, and +`PEP425 `_ + +Pip prefers Wheels where they are available. To disable this, use the +:ref:`--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 +`_ 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_`` . 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 ``[] 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 -r requirements.txt + +Then, install using :ref:`--find-links <--find-links>` and :ref:`--no-index <--no-index>`:: + +$ pip install --no-index --find-links=[file://] -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 +`_, +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 +`_ variable. This mode +of installation can be turned on by specifying the :ref:`--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 `. + 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 + `_ for plans to add hash + confirmation to pip, or a new "lock file" notion, but for now, know that the `peep + project `_ offers this feature on top of pip + using requirements file comments. + + +.. _PyPI: http://pypi.python.org/pypi/ diff --git a/pip/commands/install.py b/pip/commands/install.py index 25ab1d414..803fa262a 100644 --- a/pip/commands/install.py +++ b/pip/commands/install.py @@ -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'