mirror of
https://github.com/kennethreitz/pipenv.git
synced 2026-06-05 14:50:16 +00:00
Ben Kraft
3f13e8dfd3
When importing from requirements.txt, it may be useful to keep the versions of packages you have for the moment, while unpinning them for the future. This is already supported via `--keep-outdated`; this commit adds a mention to the docs. Fixes #908.
367 lines
13 KiB
ReStructuredText
367 lines
13 KiB
ReStructuredText
.. _basic:
|
||
|
||
Basic Usage of Pipenv
|
||
=====================
|
||
|
||
.. image:: https://farm4.staticflickr.com/3931/33173826122_b7ee8f1a26_k_d.jpg
|
||
|
||
This document covers some of Pipenv's more basic features.
|
||
|
||
☤ Example Pipfile & Pipfile.lock
|
||
--------------------------------
|
||
|
||
.. _example_files:
|
||
|
||
Here is a simple example of a ``Pipfile`` and the resulting ``Pipfile.lock``.
|
||
|
||
Example Pipfile
|
||
///////////////
|
||
|
||
::
|
||
|
||
[[source]]
|
||
url = "https://pypi.python.org/simple"
|
||
verify_ssl = true
|
||
name = "pypi"
|
||
|
||
[packages]
|
||
requests = "*"
|
||
|
||
|
||
[dev-packages]
|
||
pytest = "*"
|
||
|
||
|
||
Example Pipfile.lock
|
||
////////////////////
|
||
|
||
::
|
||
|
||
{
|
||
"_meta": {
|
||
"hash": {
|
||
"sha256": "8d14434df45e0ef884d6c3f6e8048ba72335637a8631cc44792f52fd20b6f97a"
|
||
},
|
||
"host-environment-markers": {
|
||
"implementation_name": "cpython",
|
||
"implementation_version": "3.6.1",
|
||
"os_name": "posix",
|
||
"platform_machine": "x86_64",
|
||
"platform_python_implementation": "CPython",
|
||
"platform_release": "16.7.0",
|
||
"platform_system": "Darwin",
|
||
"platform_version": "Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64",
|
||
"python_full_version": "3.6.1",
|
||
"python_version": "3.6",
|
||
"sys_platform": "darwin"
|
||
},
|
||
"pipfile-spec": 5,
|
||
"requires": {},
|
||
"sources": [
|
||
{
|
||
"name": "pypi",
|
||
"url": "https://pypi.python.org/simple",
|
||
"verify_ssl": true
|
||
}
|
||
]
|
||
},
|
||
"default": {
|
||
"certifi": {
|
||
"hashes": [
|
||
"sha256:54a07c09c586b0e4c619f02a5e94e36619da8e2b053e20f594348c0611803704",
|
||
"sha256:40523d2efb60523e113b44602298f0960e900388cf3bb6043f645cf57ea9e3f5"
|
||
],
|
||
"version": "==2017.7.27.1"
|
||
},
|
||
"chardet": {
|
||
"hashes": [
|
||
"sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691",
|
||
"sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae"
|
||
],
|
||
"version": "==3.0.4"
|
||
},
|
||
"idna": {
|
||
"hashes": [
|
||
"sha256:8c7309c718f94b3a625cb648ace320157ad16ff131ae0af362c9f21b80ef6ec4",
|
||
"sha256:2c6a5de3089009e3da7c5dde64a141dbc8551d5b7f6cf4ed7c2568d0cc520a8f"
|
||
],
|
||
"version": "==2.6"
|
||
},
|
||
"requests": {
|
||
"hashes": [
|
||
"sha256:6a1b267aa90cac58ac3a765d067950e7dbbf75b1da07e895d1f594193a40a38b",
|
||
"sha256:9c443e7324ba5b85070c4a818ade28bfabedf16ea10206da1132edaa6dda237e"
|
||
],
|
||
"version": "==2.18.4"
|
||
},
|
||
"urllib3": {
|
||
"hashes": [
|
||
"sha256:06330f386d6e4b195fbfc736b297f58c5a892e4440e54d294d7004e3a9bbea1b",
|
||
"sha256:cc44da8e1145637334317feebd728bd869a35285b93cbb4cca2577da7e62db4f"
|
||
],
|
||
"version": "==1.22"
|
||
}
|
||
},
|
||
"develop": {
|
||
"py": {
|
||
"hashes": [
|
||
"sha256:2ccb79b01769d99115aa600d7eed99f524bf752bba8f041dc1c184853514655a",
|
||
"sha256:0f2d585d22050e90c7d293b6451c83db097df77871974d90efd5a30dc12fcde3"
|
||
],
|
||
"version": "==1.4.34"
|
||
},
|
||
"pytest": {
|
||
"hashes": [
|
||
"sha256:b84f554f8ddc23add65c411bf112b2d88e2489fd45f753b1cae5936358bdf314",
|
||
"sha256:f46e49e0340a532764991c498244a60e3a37d7424a532b3ff1a6a7653f1a403a"
|
||
],
|
||
"version": "==3.2.2"
|
||
}
|
||
}
|
||
}
|
||
|
||
☤ General Recommendations & Version Control
|
||
-------------------------------------------
|
||
|
||
- Generally, keep both ``Pipfile`` and ``Pipfile.lock`` in version control.
|
||
- Do not keep ``Pipfile.lock`` in version control if multiple versions of Python are being targeted.
|
||
- Specify your target Python version in your `Pipfile`'s ``[requires]`` section. Ideally, you should only have one target Python version, as this is a deployment tool.
|
||
- ``pipenv install`` is fully compatible with ``pip install`` syntax, for which the full documentation can be found `here <https://pip.pypa.io/en/stable/user_guide/#installing-packages>`_.
|
||
|
||
|
||
|
||
☤ Example Pipenv Workflow
|
||
-------------------------
|
||
|
||
Clone / create project repository::
|
||
|
||
…
|
||
$ cd myproject
|
||
|
||
Install from Pipfile, if there is one::
|
||
|
||
$ pipenv install
|
||
|
||
Or, add a package to your new project::
|
||
|
||
$ pipenv install <package>
|
||
|
||
This will create a ``Pipfile`` if one doesn't exist. If one does exist, it will automatically be edited with the new package your provided.
|
||
|
||
Next, activate the Pipenv shell::
|
||
|
||
$ pipenv shell
|
||
$ python --version
|
||
…
|
||
|
||
.. _initialization:
|
||
|
||
☤ Example Pipenv Upgrade Workflow
|
||
---------------------------------
|
||
|
||
- Find out what's changed upstream: ``$ pipenv update --outdated``.
|
||
- Upgrade packages, two options:
|
||
a. Want to upgrade everything? Just do ``$ pipenv update``.
|
||
b. Want to upgrade packages one-at-a-time? ``$ pipenv update <pkg>`` for each outdated package.
|
||
|
||
☤ Importing from requirements.txt
|
||
---------------------------------
|
||
|
||
If you only have a ``requirements.txt`` file available when running ``pipenv install``,
|
||
pipenv will automatically import the contents of this file and create a ``Pipfile`` for you.
|
||
|
||
You can also specify ``$ pipenv install -r path/to/requirements.txt`` to import a requirements file.
|
||
|
||
If your requirements file has version numbers pinned, you'll likely want to edit the new ``Pipfile``
|
||
to remove those, and let ``pipenv`` keep track of pinning. If you want to keep the pinned versions
|
||
in your ``Pipfile.lock`` for now, run ``pipenv lock --keep-outdated``. Make sure to
|
||
`upgrade <#initialization>`_ soon!
|
||
|
||
.. _specifying_versions:
|
||
|
||
☤ Specifying Versions of a Package
|
||
----------------------------------
|
||
|
||
To tell pipenv to install a specific version of a library, the usage is simple::
|
||
|
||
$ pipenv install requests==2.13.0
|
||
|
||
This will update your ``Pipfile`` to reflect this requirement, automatically.
|
||
|
||
|
||
☤ Specifying Versions of Python
|
||
-------------------------------
|
||
|
||
To create a new virtualenv, using a specific version of Python you have installed (and
|
||
on your ``PATH``), use the ``--python VERSION`` flag, like so:
|
||
|
||
Use Python 3::
|
||
|
||
$ pipenv --python 3
|
||
|
||
Use Python3.6::
|
||
|
||
$ pipenv --python 3.6
|
||
|
||
Use Python 2.7.14::
|
||
|
||
$ pipenv --python 2.7.14
|
||
|
||
When given a Python version, like this, Pipenv will automatically scan your system for a Python that matches that given version.
|
||
|
||
If a ``Pipfile`` hasn't been created yet, one will be created for you, that looks like this::
|
||
|
||
[[source]]
|
||
url = "https://pypi.python.org/simple"
|
||
verify_ssl = true
|
||
|
||
[dev-packages]
|
||
|
||
[packages]
|
||
|
||
[requires]
|
||
python_version = "3.6"
|
||
|
||
Note the inclusion of ``[requires] python_version = "3.6"``. This specifies that your application requires this version
|
||
of Python, and will be used automatically when running ``pipenv install`` against this ``Pipfile`` in the future
|
||
(e.g. on other machines). If this is not true, feel free to simply remove this section.
|
||
|
||
If you don't specify a Python version on the command–line, either the ``[requires]`` ``python_full_version`` or ``python_version`` will be selected
|
||
automatically, falling back to whatever your system's default ``python`` installation is, at time of execution.
|
||
|
||
|
||
☤ Editable Dependencies (e.g. ``-e .`` )
|
||
----------------------------------------
|
||
|
||
You can tell Pipenv to install a path as editable — often this is useful for
|
||
the current working directory when working on packages::
|
||
|
||
$ pipenv install --dev -e .
|
||
|
||
$ cat Pipfile
|
||
...
|
||
[dev-packages]
|
||
"e1839a8" = {path = ".", editable = true}
|
||
...
|
||
|
||
Note that all sub-dependencies will get added to the ``Pipfile.lock`` as well.
|
||
|
||
.. note:: Sub-dependencies are **not** added to the ``Pipfile.lock`` if you
|
||
leave the ``-e`` option out.
|
||
|
||
|
||
.. _environment_management:
|
||
|
||
☤ Environment Management with Pipenv
|
||
------------------------------------
|
||
|
||
The three primary commands you'll use in managing your pipenv environment are
|
||
``$ pipenv install``, ``$ pipenv uninstall``, and ``$ pipenv lock``.
|
||
|
||
.. _pipenv_install:
|
||
|
||
$ pipenv install
|
||
////////////////
|
||
|
||
``$ pipenv install`` is used for installing packages into the pipenv virtual environment
|
||
and updating your Pipfile.
|
||
|
||
Along with the basic install command, which takes the form::
|
||
|
||
$ pipenv install [package names]
|
||
|
||
The user can provide these additional parameters:
|
||
|
||
- ``--two`` — Performs the installation in a virtualenv using the system ``python2`` link.
|
||
- ``--three`` — Performs the installation in a virtualenv using the system ``python3`` link.
|
||
- ``--python`` — Performs the installation in a virtualenv using the provided Python interpreter.
|
||
|
||
.. warning:: None of the above commands should be used together. They are also
|
||
**destructive** and will delete your current virtualenv before replacing
|
||
it with an appropriately versioned one.
|
||
|
||
.. note:: The virtualenv created by Pipenv may be different from what you were expecting.
|
||
Dangerous characters (i.e. ``$`!*@"`` as well as space, line feed, carriage return,
|
||
and tab) are converted to underscores. Additionally, the full path to the current
|
||
folder is encoded into a "slug value" and appended to ensure the virtualenv name
|
||
is unique.
|
||
|
||
- ``--dev`` — Install both ``develop`` and ``default`` packages from ``Pipfile.lock``.
|
||
- ``--system`` — Use the system ``pip`` command rather than the one from your virtualenv.
|
||
- ``--ignore-pipfile`` — Ignore the ``Pipfile`` and install from the ``Pipfile.lock``.
|
||
- ``--skip-lock`` — Ignore the ``Pipfile.lock`` and install from the ``Pipfile``. In addition, do not write out a ``Pipfile.lock`` reflecting changes to the ``Pipfile``.
|
||
|
||
.. _pipenv_uninstall:
|
||
|
||
$ pipenv uninstall
|
||
//////////////////
|
||
|
||
``$ pipenv uninstall`` supports all of the parameters in `pipenv install <#pipenv-install>`_,
|
||
as well as two additional options, ``--all`` and ``--all-dev``.
|
||
|
||
- ``--all`` — This parameter will purge all files from the virtual environment,
|
||
but leave the Pipfile untouched.
|
||
|
||
- ``--all-dev`` — This parameter will remove all of the development packages from
|
||
the virtual environment, and remove them from the Pipfile.
|
||
|
||
|
||
.. _pipenv_lock:
|
||
|
||
$ pipenv lock
|
||
/////////////
|
||
|
||
``$ pipenv lock`` is used to create a ``Pipfile.lock``, which declares **all** dependencies (and sub-dependencies) of your project, their latest available versions, and the current hashes for the downloaded files. This ensures repeatable, and most importantly *deterministic*, builds.
|
||
|
||
☤ About Shell Configuration
|
||
---------------------------
|
||
|
||
Shells are typically misconfigured for subshell use, so ``$ pipenv shell --fancy`` may produce unexpected results. If this is the case, try ``$ pipenv shell``, which uses "compatibility mode", and will attempt to spawn a subshell despite misconfiguration.
|
||
|
||
A proper shell configuration only sets environment variables like ``PATH`` during a login session, not during every subshell spawn (as they are typically configured to do). In fish, this looks like this::
|
||
|
||
if status --is-login
|
||
set -gx PATH /usr/local/bin $PATH
|
||
end
|
||
|
||
You should do this for your shell too, in your ``~/.profile`` or ``~/.bashrc`` or wherever appropriate.
|
||
|
||
.. note:: The shell launched in interactive mode. This means that if your shell reads its configuration from a specific file for interactive mode (e.g. bash by default looks for a ``~/.bashrc`` configuration file for interactive mode), then you'll need to modify (or create) this file.
|
||
|
||
|
||
☤ A Note about VCS Dependencies
|
||
-------------------------------
|
||
|
||
Pipenv will resolve the sub–dependencies of VCS dependencies, but only if they are installed in editable mode::
|
||
|
||
$ pipenv install -e git+https://github.com/requests/requests.git#egg=requests
|
||
|
||
$ cat Pipfile
|
||
[packages]
|
||
requests = {git = "https://github.com/requests/requests.git", editable=true}
|
||
|
||
If editable is not true, sub–dependencies will not be resolved.
|
||
|
||
For more information about other options available when specifying VCS dependencies, please check the `Pipfile spec <https://github.com/pypa/pipfile>`__.
|
||
|
||
|
||
☤ Pipfile.lock Security Features
|
||
--------------------------------
|
||
|
||
``Pipfile.lock`` takes advantage of some great new security improvements in ``pip``.
|
||
By default, the ``Pipfile.lock`` will be generated with the sha256 hashes of each downloaded
|
||
package. This will allow ``pip`` to guarantee you're installing what you intend to when
|
||
on a compromised network, or downloading dependencies from an untrusted PyPI endpoint.
|
||
|
||
We highly recommend approaching deployments with promoting projects from a development
|
||
environment into production. You can use ``pipenv lock`` to compile your dependencies on
|
||
your development environment and deploy the compiled ``Pipfile.lock`` to all of your
|
||
production environments for reproducible builds.
|
||
|
||
.. note:
|
||
|
||
If you'd like a ``requirements.txt`` output of the lockfile, run ``$ pipenv lock -r``.
|
||
This will include all hashes, however (which is great!). To get a ``requirements.txt``
|
||
without hashes, use ``$ pipenv run pip freeze``.
|
||
|