.. _advanced: Advanced Usage of Pipenv ======================== This document covers some of pipenv's more advanced features. ☤ Example Pipfile & Pipfile.lock -------------------------------- .. _example_files: Here is a simple example of a ``Pipfile`` and the resulting ``Pipfile.lock``. Example Pipfile /////////////// :: [dev-packages] pytest = "*" [packages] requests = "*" Example Pipfile.lock //////////////////// :: { "default": { "requests": { "version": "==2.13.0", "hash": "sha256:1a720e8862a41aa22e339373b526f508ef0c8988baf48b84d3fc891a8e237efb" } }, "develop": { "packaging": { "version": "==16.8", "hash": "sha256:99276dc6e3a7851f32027a68f1095cd3f77c148091b092ea867a351811cfe388" }, "pytest": { "version": "==3.0.6", "hash": "sha256:da0ab50c7eec0683bc24f1c1137db1f4111752054ecdad63125e7ec71316b813" }, "setuptools": { "version": "==34.1.0", "hash": "sha256:edd9d39782fe38b9c533002b2e6fdf06498793cbd29266accdcc519431d4b7ba" }, "pyparsing": { "version": "==2.1.10", "hash": "sha256:67101d7acee692962f33dd30b5dce079ff532dd9aa99ff48d52a3dad51d2fe84" }, "py": { "version": "==1.4.32", "hash": "sha256:2d4bba2e25fff58140e6bdce1e485e89bb59776adbe01d490baa6b1f37a3dd6b" }, "six": { "version": "==1.10.0", "hash": "sha256:0ff78c403d9bccf5a425a6d31a12aa6b47f1c21ca4dc2573a7e2f32a97335eb1" }, "appdirs": { "version": "==1.4.0", "hash": "sha256:85e58578db8f29538f3109c11250c2a5514a2fcdc9890d9b2fe777eb55517736" } }, "_meta": { "sources": [ { "url": "https://pypi.python.org/simple", "verify_ssl": true } ], "requires": {}, "hash": { "sha256": "08e3181df84d04301c9d435357ec9cf43c4a491d79a1ada682cce8936c492f49" } } } .. _initialization: ☤ 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. .. _specifying_versions: ☤ Specifying Versions --------------------- 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. .. _proper_installation: ☤ Fancy Installation of Pipenv ------------------------------ To install pipenv in a fancy way, we recommend using `pipsi `_. Pipsi is a powerful tool which allows you to install Python scripts into isolated virtual environments. To install pipsi, first run this:: $ curl https://raw.githubusercontent.com/mitsuhiko/pipsi/master/get-pipsi.py | python Follow the instructions, you'll have to update your ``PATH``. Then, simply run:: $ pipsi install pew $ pipsi install pipenv To upgrade pipenv at any time:: $ pipsi upgrade pipenv This will install both ``pipenv`` and ``pew`` (one of our dependencies) in an isolated virtualenv, so it doesn't interfere with the rest of your Python installation! .. _pragmatic_installation: ☤ Pragmatic Installation of Pipenv ---------------------------------- If you have a working installation of pip, and maintain certain "toolchain" type Python modules as global utilities in your user enviornment, pip `user installs `_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software. To install:: $ pip install --user pipenv For more information see the `user installs documentation `_, but to add the installed cli tools from a pip user install to your path, add the output of:: $ python -c "import site; import os; print(os.path.join(site.USER_BASE, 'bin'))" To upgrade pipenv at any time:: $ pip install --user --upgrade pipenv .. _crude_installation: ☤ Crude Installation of Pipenv ------------------------------ If you don't even have pip installed, you can use this crude installation method, which will boostrap your whole system:: $ curl https://github.com/kennethreitz/pipenv/raw/master/get-pipenv.py | python Congratulations, you now have pip and Pipenv installed! .. _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 intepreter. .. 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. - ``--lock`` — Generate a new ``Pipfile.lock`` adding the newly installed packages. - ``--ignore-pipfile`` — Ignore the ``Pipfile`` and install from the ``Pipfile.lock``. .. _pipenv_uninstall $ pipenv uninstall ////////////////// ``$ pipenv uninstall`` supports all of the parameters in `pipenv install <#pipenv-install>`_, as well as one additonal, ``--all``. - ``--all`` — This parameter will purge all files from the virtual environment, but leave the Pipfile untouched. .. _pipenv_lock $ pipenv lock ///////////// ``$ pipenv lock`` is used to create a ``Pipfile.lock``, which declares **all** dependencies (and sub-depdendencies) of your project, their latest available versions, and the current hashes for the downloaded files. This ensures repeatable, and most importantly *deterministic*, builds. ☤ Configuration With Environment Variables ------------------------------------------ ``pipenv`` comes with a handful of options that can be enabled via shell environment variables. To activate them, simply create the variable in your shell and pipenv will detect it. - ``PIPENV_SHELL_COMPAT`` — Toggle from our default ``pipenv shell`` mode to classic. (Suggested for use with pyenv). - ``PIPENV_VENV_IN_PROJECT`` — Toggle for detecting a ``.venv`` in your project directory and using it over the default environment manager, ``pew``. - ``PIPENV_COLORBLIND`` — Disable terminal colors, for some reason. - ``PIPENV_NOSPIN`` — Disable terminal spinner, for cleaner logs. - ``PIPENV_MAX_DEPTH`` — Set to an integer for the maximum number of directories to search for a Pipfile. - ``PIPENV_TIMEOUT`` — Set to an integer for the max number of seconds pipenv will wait for virtualenv creation to complete. Defaults to 120 seconds. - ``PIPENV_IGNORE_VIRTUALENVS`` — Set to disable automatically using an activated virtualenv over the current project. ☤ Custom Virtual Environment Location ------------------------------------- Pipenv's underlying ``pew`` dependency will automatically honor the ``WORKON_HOME`` environment variable, if you have it set — so you can tell pipenv to store your virtual environments wherever you want, e.g.:: export WORKON_HOME=~/.venvs ☤ Testing Projects ------------------ While pipenv is still a relatively new project, it's already being used in projects like `Requests`_. Specifically for transitioning to the new Pipfile format and running the test suite. We've currently tested deployments with both `Travis-CI`_ and `tox`_ with success. .. note:: It's highly recommended to run ``pipenv lock`` before installing on a CI platform, due to possible hash conflicts between system binaries. Travis CI ///////// An example Travis CI setup can be found in `Requests`_. The project uses a Makefile to define common functions such as its ``init`` and ``tests`` commands. Here is a stripped down example ``.travis.yml``:: language: python python: - "2.6" - "2.7" - "3.3" - "3.4" - "3.5" - "3.6" - "3.7dev" # command to install dependencies install: "make" # command to run tests script: - make test and the corresponding Makefile:: init: pip install pipenv pipenv install --dev test: pipenv run py.test tests Tox Automation Project ////////////////////// Alternatively, you can configure a ``tox.ini`` like the one below for both local and external testing:: [tox] envlist = flake8-py3, py26, py27, py33, py34, py35, py36, pypy [testenv] passenv=HOME deps = pipenv commands= pipenv install --dev pipenv run py.test tests [testenv:flake8-py3] passenv=HOME basepython = python3.4 commands= {[testenv]deps} pipenv install --dev pipenv run flake8 --version pipenv run flake8 setup.py docs project test .. note:: With Pipenv's default configuration, you'll need to use tox's ``passenv`` parameter to pass your shell's ``HOME`` variable. .. _Requests: https://github.com/kennethreitz/requests .. _tox: https://tox.readthedocs.io/en/latest/ .. _Travis-CI: https://travis-ci.org/ ☤ 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 a sha256 hash 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:: Due to different hashes being generated between wheels on different systems, you will find hashes don't work cross-platform or between Python versions. To solve this, you may either compile the lock file on your target system, or use the less secure ``pipenv install --ignore-hashes``. If you wish to produce a Pipfile.lock without hashes, you may also use ``pipenv lock --no-hashes``. ☤ Shell Completion ------------------ Set ``_PIPENV_COMPLETE`` and then source the output of the program. For example, with ``fish``, put this in your ``~/.config/fish/completions/pipenv.fish``:: eval (env _PIPENV_COMPLETE=source-fish pipenv) Magic shell completions are now enabled! ✨🍰✨