diff --git a/docs/basics.rst b/docs/basics.rst index 709f0b08..b22b4aeb 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -182,13 +182,38 @@ in your ``Pipfile.lock`` for now, run ``pipenv lock --keep-outdated``. Make sur ☤ Specifying Versions of a Package ---------------------------------- -To tell pipenv to install a specific version of a library, the usage is simple:: +You can specify versions of a package using the `Semantic Versioning scheme `_ +(i.e. ``major.minor.micro``). - $ pipenv install requests==2.13.0 +For example, to install requests you can use: :: + + $ pipenv install requests~=1.2 # equivalent to requests~=1.2.0 + +Pipenv will install version ``1.2`` and any minor update, but not ``2.0``. This will update your ``Pipfile`` to reflect this requirement, automatically. -For other version specifiers, see `the relevant section of PEP-440`_. +In general, Pipenv uses the same specifier format as pip. However, note that according to `PEP 440`_ , you can't use versions containing a hyphen or a plus sign. + +.. _`PEP 440`: + +To make inclusive or exclusive version comparisons you can use: :: + + $ pipenv install "requests>=1.4" # will install a version equal or larger than 1.4.0 + $ pipenv install "requests<=2.13" # will install a version equal or lower than 2.13.0 + $ pipenv install "requests>2.19" # will install 2.19.1 but not 2.19.0 + +.. note:: The use of ``" "`` around the package and version specification is highly recommended + to avoid issues with `Input and output redirection `_ + in Unix-based operating systems. + +The use of ``~=`` is preferred over the ``==`` identifier as the former prevents pipenv from updating the packages: :: + + $ pipenv install "requests~=2.2" # locks the major version of the package (this is equivalent to using ==2.*) + +To avoind installing a specific version you can use the ``!=`` identifier. + +For an in depth explanation of the valid identifiers and more complex use cases check `the relevant section of PEP-440`_. .. _`the relevant section of PEP-440`: https://www.python.org/dev/peps/pep-0440/#version-specifiers>