为人类服务的Python开发工作流工具

---

Pipenv 的目标是把所有包管理工具(bundler, composer, npm, cargo, yarn等)中的最佳实践带到Python的世界。 Windows在这里是第一等公民。

它能为你的项目自动创建、管理虚拟环境，同时，当你安装、卸载包时，它能自动在你的 Pipfile 中添加、删除记录。它还会为你生成一个相当重要的 Pipfile.lock 文件，用来产生一致性的构建。

Pipenv的主要目的是为应用的开发者和使用者能容易地设置好一个工作环境。关于库与应用的区别以及 setup.py 与 Pipfile 在指定依赖上的使用，请参考 ☤ Pipfile vs setup.py 。

Pipenv要解决的问题，是多方面的：

• 你无需再分开使用 pip 和 virtualenv 了，他们是一起工作的。
• 管理一个 requirements.txt` `文件 `可能会有很多问题 <https://www.kennethreitz.org/essays/a-better-pip-workflow>`_ ，所以Pipenv使用 ``Pipfile 与 Pipfile.lock 来将抽象依赖声明与最近的已验证的依赖版本分离。
• 在各处都尽可能使用哈希值。自动暴露安全缺陷。
• 为了尽量避免 过期组件的安全漏洞 ，强烈鼓励使用依赖的最新版本。
• 让你看到你的依赖图 ( $ pipenv graph )
• 通过 .env 文件让开发工作流水化。

你可以在你的浏览器中快速预览Pipenv

今天就安装Pipenv吧！

如果你在用MacOS，你可以使用Homebrew方便地安装Pipenv。你也可以在Linux系统上的Linuxbrew中使用相同的命令

$ brew install pipenv

或者，如果你用的是Fedora 28

$ sudo dnf install pipenv

如果你的系统不在上述列表中，参考 ☤ 安装Pipenv 一章中的安装指引。

✨🍰✨

Pipenv与虚拟环境

这篇教程将带你安装与使用Python包。

它阐明了如何安装和使用必要的工具，强力推荐了一些最佳实践。时刻记住Python被用于非常多的场景，取决于你如何发布软件，依赖的具体管理方式也可能千差万别。这里展示的指引不仅对大多数开发部署环境和网络服务 (包括web应用) 都是适用的，而且对于管理开发测试环境，也适用于任何类型的项目。

注解

这篇指引是基于Python 3编写的，但对Python 2.7也是适用的——如果你还在用的话。

☤ 确保你已经安装好了Python和pip

在进行接下来的步骤之前，请确保你已经安装好了Python并且可以从命令行启动。你可以用下面的简单的命令来做检查:

$ python --version

你应该能看到类似于 3.6.2 的输出。如果你系统上没有Python，请从 python.org 安装最新的3.x版本，或者参考 Python银河系漫游指南 中的 Installing Python 一节。

注解

如果你是新手并看到了这样的错误:

>>> python
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'python' is not defined

这是因为这条命令应该在 shell (也称为 终端 或 控制台) 中运行。参考Python入门的 getting started tutorial 学习如何使用操作系统的shell与Python交互。

此外，你还需要确保pip是可用的。你可以运行下面的命令来检查:

$ pip --version
pip 9.0.1

如果你从源代码安装Python，从 python.org 上提供的安装器，从 Homebrew 或是从 Linuxbrew 安装，都应该自带了pip。但如果你是Linux用户并且通过系统的包管理器安装的Python，你可能需要单独安装 pip 。

如果你打算通过Homebrew或者Linuxbrew安装Python则可以跳过此步骤。Homebrew/Linuxbrew安装器会自动帮你装好pip。

☤ 安装Pipenv

Pipenv is a dependency manager for Python projects. If you’re familiar with Node.js’s npm or Ruby’s bundler, it is similar in spirit to those tools. While pip can install Python packages, Pipenv is recommended as it’s a higher-level tool that simplifies dependency management for common use cases.

☤ Isolated Installation of Pipenv with Pipx

`Pipx`_ is a tool to help you install and run end-user applications written in Python. It installs applications into an isolated and clean environment on their own. To install pipx, just run:

$ pip install --user pipx

Once you have pipx ready on your system, continue to install Pipenv:

$ pipx install pipenv

☤ 用普通方式安装Pipenv

If you have a working installation of pip, and maintain certain “tool-chain” type Python modules as global utilities in your user environment, 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.

安装方法:

$ pip install --user pipenv

注解

这会执行一次 user installation 来避免破坏系统的包。如果安装完成后 pipenv 在命令行中不可用，你需要把 user base 的二进制执行文件目录添加到 PATH 变量中。

在Linux和macOS上你可以使用 python -m site --user-base 的输出末尾加上 /bin 来获取用户的二进制执行文件目录。举例来说，这一般会输出 ~/.local ( ~ 展开成你的用户根目录的绝对路径)，所以你需要将 ~/.local/bin 加到你的 PATH 中。你可以通过修改 ~/.profile`_ 文件永久设置 ``PATH 。

在Windows上，你可以运行 python -m site --user-site，然后将输出中的 site-packages 替换为 Scripts 即可得到用户的二进制执行文件目录。举例来说，如果它输出了 C:\Users\Username\AppData\Roaming\Python36\site-packages ，你就要设置 PATH , 加上 C:\Users\Username\AppData\Roaming\Python36\Scripts 。你可以在 Control Panel 中永久设置 PATH 变量。为了让 PATH 的改变生效，可能需要注销。

更多信息，请参阅 用户安装文档 。

在任何时候，如果要更新Pipenv:

$ pip install --user --upgrade pipenv

☤ 暴力安装Pipenv

如果你连pip都没有安装，你可以使用这个暴力安装法安装一整套系统:

$ curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python

☤ Homebrew Installation of Pipenv(Discouraged)

Homebrew 是一款macOS上的开源包管理系统。对于Linux用户，`Linuxbrew`是它的Linux移植版本。

通过Homebrew或Linuxbrew安装Pipenv时会将Pipenv及其依赖都放在一个隔离的虚拟环境中，这样就不会影响你其他的Python安装的包。

你装好了Homebrew或Linuxbrew之后只要运行:

$ brew install pipenv

在任何时候，如果要更新Pipenv:

$ brew upgrade pipenv

注解

Homebrew installation is discouraged because each time the Homebrew Python is upgraded, which Pipenv depends on, users have to re-install Pipenv, and perhaps all virtual environments managed by it.

☤ 在项目中安装依赖包

Pipenv是分项目管理依赖的。要安装依赖包，进入你的项目目录 (或者就一个空目录)，运行:

$ cd myproject
$ pipenv install requests

这样，Pipenv就会将 Requests 这个优秀的库安装好，并且在你的项目目录中创建一个 Pipfile 文件。Pipfile 文件是用来跟踪项目需要的依赖，以备以后如果你将项目分享给其他人，重新安装时使用。你应该得到类似于下面的输出 (具体路径会有所不同):

Creating a Pipfile for this project...
Creating a virtualenv for this project...
Using base prefix '/usr/local/Cellar/python3/3.6.2/Frameworks/Python.framework/Versions/3.6'
New python executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python3.6
Also creating executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python
Installing setuptools, pip, wheel...done.

Virtualenv location: ~/.local/share/virtualenvs/tmp-agwWamBd
Installing requests...
Collecting requests
  Using cached requests-2.18.4-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests)
  Using cached idna-2.6-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests)
  Using cached urllib3-1.22-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests)
  Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests)
  Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Installing collected packages: idna, urllib3, chardet, certifi, requests
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22

Adding requests to Pipfile's [packages]...
P.S. You have excellent taste! ✨ 🍰 ✨

☤ 使用安装好的包

现在Requests已经安装好了，你可以创建一个简单的 main.py 文件来使用它：

import requests

response = requests.get('https://httpbin.org/ip')

print('Your IP is {0}'.format(response.json()['origin']))

然后你可以使用 pipenv run 来运行此脚本:

$ pipenv run python main.py

你应该会得到类似于下面的输出：

Your IP is 8.8.8.8

使用 $ pipenv run 可以确保你安装好的包在你的脚本中可用。也可以通过 $ pipenv shell 启动一个新的终端环境，在其中所有的命令都可以访问你安装好的包。

☤ 虚拟环境映射说明

• Pipenv会自动将项目映射到对应的虚拟环境。
• 虚拟环境会以项目的根目录加上全路径的hash值作为环境名称 (例如 my_project-a3de50) 存储起来。
• 如果项目路径被更改，就会破坏这个默认的映射，这样pipenv就无法找到和使用项目的虚拟环境。
• 你可以在你的.bashrc/.zshrc (或者其他终端配置文件中) 加入 export PIPENV_VENV_IN_PROJECT=1 来让虚拟环境创建到你的项目目录中，这样就避免了以后路径更改带来的问题。

☤ 后续步骤

恭喜，你已经学会了如何安装使用Python包！✨ 🍰 ✨

Release and Version History

2020.8.13 (2020-08-13)

Bug Fixes

• Fixed behaviour of pipenv uninstall --all-dev. From now on it does not uninstall regular packages. #3722
• Fix a bug that incorrect Python path will be used when --system flag is on. #4315
• Fix falsely flagging a Homebrew installed Python as a virtual environment #4316
• Fix a bug that pipenv uninstall throws an exception that does not exist. #4321
• Fix a bug that Pipenv can’t locate the correct file of special directives in setup.cfg of an editable package. #4335
• Fix a bug that setup.py can’t be parsed correctly when the assignment is type-annotated. #4342
• Fix a bug that pipenv graph throws an exception that PipenvCmdError(cmd_string, c.out, c.err, return_code). #4388
• Do not copy the whole directory tree of local file package. #4403
• Correctly detect whether Pipenv in run under an activated virtualenv. #4412

Vendored Libraries

• Update requirementslib to 1.5.12. #4385
• • Update requirements to 1.5.13.
  • Update pip-shims to 0.5.3. #4421

2020.6.2 (2020-06-02)

Features & Improvements

• Pipenv will now detect existing venv and virtualenv based virtual environments more robustly. #4276

Bug Fixes

• + signs in URL authentication fragments will no longer be incorrectly replaced with space ( `` `` ) characters. #4271
• Fixed a regression which caused Pipenv to fail when running under /. #4273
• setup.py files with version variables read from os.environ are now able to be parsed successfully. #4274
• Fixed a bug which caused Pipenv to fail to install packages in a virtual environment if those packages were already present in the system global environment. #4276
• Fix a bug that caused non-specific versions to be pinned in Pipfile.lock. #4278
• Corrected a missing exception import and invalid function call invocations in pipenv.cli.command. #4286
• Fixed an issue with resolving packages with names defined by function calls in setup.py. #4292
• Fixed a regression with installing the current directory, or ., inside a venv based virtual environment. #4295
• Fixed a bug with the discovery of python paths on Windows which could prevent installation of environments during pipenv install. #4296
• Fixed an issue in the requirementslib AST parser which prevented parsing of setup.py files for dependency metadata. #4298
• Fix a bug where Pipenv doesn’t realize the session is interactive #4305

Vendored Libraries

• Updated requirementslib to version 1.5.11. #4292

• Updated vendored dependencies:

  • pythonfinder: 1.2.2 => 1.2.4
  • requirementslib: 1.5.9 => 1.5.10 #4302

2020.5.28 (2020-05-28)

Features & Improvements

• pipenv install and pipenv sync will no longer attempt to install satisfied dependencies during installation. #3057, #3506
• Added support for resolution of direct-url dependencies in setup.py files to respect PEP-508 style URL dependencies. #3148
• Added full support for resolution of all dependency types including direct URLs, zip archives, tarballs, etc.
  • Improved error handling and formatting.
  • Introduced improved cross platform stream wrappers for better stdout and stderr consistency. #3298
• For consistency with other commands and the --dev option description, pipenv lock --requirements --dev now emits both default and development dependencies. The new --dev-only option requests the previous behaviour (e.g. to generate a dev-requirements.txt file). #3316
• Pipenv will now successfully recursively lock VCS sub-dependencies. #3328
• Added support for --verbose output to pipenv run. #3348
• Pipenv will now discover and resolve the intrinsic dependencies of all VCS dependencies, whether they are editable or not, to prevent resolution conflicts. #3368
• Added a new environment variable, PIPENV_RESOLVE_VCS, to toggle dependency resolution off for non-editable VCS, file, and URL based dependencies. #3577
• Added the ability for Windows users to enable emojis by setting PIPENV_HIDE_EMOJIS=0. #3595
• Allow overriding PIPENV_INSTALL_TIMEOUT environment variable (in seconds). #3652
• Allow overriding PIP_EXISTS_ACTION evironment variable (value is passed to pip install). Possible values here: https://pip.pypa.io/en/stable/reference/pip/#exists-action-option Useful when you need to PIP_EXISTS_ACTION=i (ignore existing packages) - great for CI environments, where you need really fast setup. #3738
• Pipenv will no longer forcibly override PIP_NO_DEPS on all vcs and file dependencies as resolution happens on these in a pre-lock step. #3763
• Improved verbose logging output during pipenv lock will now stream output to the console while maintaining a spinner. #3810
• Added support for automatic python installs via asdf and associated PIPENV_DONT_USE_ASDF environment variable. #4018
• Pyenv/asdf can now be used whether or not they are available on PATH. Setting PYENV_ROOT/ASDF_DIR in a Pipenv’s .env allows Pipenv to install an interpreter without any shell customizations, so long as pyenv/asdf is installed. #4245
• Added --key command line parameter for including personal PyUp.io API tokens when running pipenv check. #4257

Behavior Changes

• Make conservative checks of known exceptions when subprocess returns output, so user won’t see the whole traceback - just the error. #2553
• Do not touch Pipfile early and rely on it so that one can do pipenv sync without a Pipfile. #3386
• Re-enable --help option for pipenv run command. #3844
• Make sure pipenv lock -r --pypi-mirror {MIRROR_URL} will respect the pypi-mirror in requirements output. #4199

Bug Fixes

• Raise PipenvUsageError when [[source]] does not contain url field. #2373
• Fixed a bug which caused editable package resolution to sometimes fail with an unhelpful setuptools-related error message. #2722
• Fixed an issue which caused errors due to reliance on the system utilities which and where which may not always exist on some systems. - Fixed a bug which caused periodic failures in python discovery when executables named python were not present on the target $PATH. #2783
• Dependency resolution now writes hashes for local and remote files to the lockfile. #3053
• Fixed a bug which prevented pipenv graph from correctly showing all dependencies when running from within pipenv shell. #3071
• Fixed resolution of direct-url dependencies in setup.py files to respect PEP-508 style URL dependencies. #3148
• Fixed a bug which caused failures in warning reporting when running pipenv inside a virtualenv under some circumstances.
  • Fixed a bug with package discovery when running pipenv clean. #3298
• Quote command arguments with carets (^) on Windows to work around unintended shell escapes. #3307
• Handle alternate names for UTF-8 encoding. #3313
• Abort pipenv before adding the non-exist package to Pipfile. #3318
• Don’t normalize the package name user passes in. #3324
• Fix a bug where custom virtualenv can not be activated with pipenv shell #3339
• Fix a bug that --site-packages flag is not recognized. #3351
• Fix a bug where pipenv –clear is not working #3353
• Fix unhashable type error during $ pipenv install --selective-upgrade #3384
• Dependencies with direct PEP508 compliant VCS URLs specified in their install_requires will now be successfully locked during the resolution process. #3396
• Fixed a keyerror which could occur when locking VCS dependencies in some cases. #3404
• Fixed a bug that ValidationError is thrown when some fields are missing in source section. #3427
• Updated the index names in lock file when source name in Pipfile is changed. #3449
• Fixed an issue which caused pipenv install --help to show duplicate entries for --pre. #3479
• Fix bug causing [SSL: CERTIFICATE_VERIFY_FAILED] when Pipfile [[source]] has verify_ssl=false and url with custom port. #3502
• Fix sync --sequential ignoring pip install errors and logs. #3537
• Fix the issue that lock file can’t be created when PIPENV_PIPFILE is not under working directory. #3584
• Pipenv will no longer inadvertently set editable=True on all vcs dependencies. #3647
• The --keep-outdated argument to pipenv install and pipenv lock will now drop specifier constraints when encountering editable dependencies. - In addition, --keep-outdated will retain specifiers that would otherwise be dropped from any entries that have not been updated. #3656
• Fixed a bug which sometimes caused pipenv to fail to respect the --site-packages flag when passed with pipenv install. #3718
• Normalize the package names to lowercase when comparing used and in-Pipfile packages. #3745
• pipenv update --outdated will now correctly handle comparisons between pre/post-releases and normal releases. #3766
• Fixed a KeyError which could occur when pinning outdated VCS dependencies via pipenv lock --keep-outdated. #3768
• Resolved an issue which caused resolution to fail when encountering poorly formatted python_version markers in setup.py and setup.cfg files. #3786
• Fix a bug that installation errors are displayed as a list. #3794
• Update pythonfinder to fix a problem that python.exe will be mistakenly chosen for virtualenv creation under WSL. #3807
• Fixed several bugs which could prevent editable VCS dependencies from being installed into target environments, even when reporting successful installation. #3809
• pipenv check --system should find the correct Python interpreter when python does not exist on the system. #3819
• Resolve the symlinks when the path is absolute. #3842
• Pass --pre and --clear options to pipenv update --outdated. #3879
• Fixed a bug which prevented resolution of direct URL dependencies which have PEP508 style direct url VCS sub-dependencies with subdirectories. #3976
• Honor PIPENV_SPINNER environment variable #4045
• Fixed an issue with pipenv check failing due to an invalid API key from pyup.io. #4188
• Fixed a bug which caused versions from VCS dependencies to be included in Pipfile.lock inadvertently. #4217
• Fixed a bug which caused pipenv to search non-existent virtual environments for pip when installing using --system. #4220
• Requires-Python values specifying constraint versions of python starting from 1.x will now be parsed successfully. #4226
• Fix a bug of pipenv update --outdated that can’t print output correctly. #4229
• Fixed a bug which caused pipenv to prefer source distributions over wheels from PyPI during the dependency resolution phase. Fixed an issue which prevented proper build isolation using pep517 based builders during dependency resolution. #4231
• Don’t fallback to system Python when no matching Python version is found. #4232

Vendored Libraries

• Updated vendored dependencies:

  • attrs: 18.2.0 => 19.1.0
  • certifi: 2018.10.15 => 2019.3.9
  • cached_property: 1.4.3 => 1.5.1
  • cerberus: 1.2.0 => 1.3.1
  • click-completion: 0.5.0 => 0.5.1
  • colorama: 0.3.9 => 0.4.1
  • distlib: 0.2.8 => 0.2.9
  • idna: 2.7 => 2.8
  • jinja2: 2.10.0 => 2.10.1
  • markupsafe: 1.0 => 1.1.1
  • orderedmultidict: (new) => 1.0
  • packaging: 18.0 => 19.0
  • parse: 1.9.0 => 1.12.0
  • pathlib2: 2.3.2 => 2.3.3
  • pep517: (new) => 0.5.0
  • pexpect: 4.6.0 => 4.7.0
  • pipdeptree: 0.13.0 => 0.13.2
  • pyparsing: 2.2.2 => 2.3.1
  • python-dotenv: 0.9.1 => 0.10.2
  • pythonfinder: 1.1.10 => 1.2.1
  • pytoml: (new) => 0.1.20
  • requests: 2.20.1 => 2.21.0
  • requirementslib: 1.3.3 => 1.5.0
  • scandir: 1.9.0 => 1.10.0
  • shellingham: 1.2.7 => 1.3.1
  • six: 1.11.0 => 1.12.0
  • tomlkit: 0.5.2 => 0.5.3
  • urllib3: 1.24 => 1.25.2
  • vistir: 0.3.0 => 0.4.1
  • yaspin: 0.14.0 => 0.14.3

  • Removed vendored dependency cursor. #3298

• Updated pip_shims to support --outdated with new pip versions. #3766

• Update vendored dependencies and invocations

  • Update vendored and patched dependencies - Update patches on piptools, pip, pip-shims, ``tomlkit`
  • Fix invocations of dependencies - Fix custom ``InstallCommand` instantiation - Update ``PackageFinder` usage - Fix ``Bool` stringify attempts from ``tomlkit`

  Updated vendored dependencies:

  • attrs: `18.2.0 => `19.1.0
  • certifi: `2018.10.15 => `2019.3.9
  • cached_property: `1.4.3 => `1.5.1
  • cerberus: `1.2.0 => `1.3.1
  • click: `7.0.0 => `7.1.1
  • click-completion: `0.5.0 => `0.5.1
  • colorama: `0.3.9 => `0.4.3
  • contextlib2: `(new) => `0.6.0.post1
  • distlib: `0.2.8 => `0.2.9
  • funcsigs: `(new) => `1.0.2
  • importlib_metadata `1.3.0 => `1.5.1
  • importlib-resources: `(new) => `1.4.0
  • idna: `2.7 => `2.9
  • jinja2: `2.10.0 => `2.11.1
  • markupsafe: `1.0 => `1.1.1
  • more-itertools: `(new) => `5.0.0
  • orderedmultidict: `(new) => `1.0
  • packaging: `18.0 => `19.0
  • parse: `1.9.0 => `1.15.0
  • pathlib2: `2.3.2 => `2.3.3
  • pep517: `(new) => `0.5.0
  • pexpect: `4.6.0 => `4.8.0
  • pip-shims: `0.2.0 => `0.5.1
  • pipdeptree: `0.13.0 => `0.13.2
  • pyparsing: `2.2.2 => `2.4.6
  • python-dotenv: `0.9.1 => `0.10.2
  • pythonfinder: `1.1.10 => `1.2.2
  • pytoml: `(new) => `0.1.20
  • requests: `2.20.1 => `2.23.0
  • requirementslib: `1.3.3 => `1.5.4
  • scandir: `1.9.0 => `1.10.0
  • shellingham: `1.2.7 => `1.3.2
  • six: `1.11.0 => `1.14.0
  • tomlkit: `0.5.2 => `0.5.11
  • urllib3: `1.24 => `1.25.8
  • vistir: `0.3.0 => `0.5.0
  • yaspin: `0.14.0 => `0.14.3
  • zipp: `0.6.0

  • Removed vendored dependency cursor. #4169

• Add and update vendored dependencies to accommodate safety vendoring: - safety (none) => 1.8.7 - dparse (none) => 0.5.0 - pyyaml (none) => 5.3.1 - urllib3 1.25.8 => 1.25.9 - certifi 2019.11.28 => 2020.4.5.1 - pyparsing 2.4.6 => 2.4.7 - resolvelib 0.2.2 => 0.3.0 - importlib-metadata 1.5.1 => 1.6.0 - pip-shims 0.5.1 => 0.5.2 - requirementslib 1.5.5 => 1.5.6 #4188

• Updated vendored pip => 20.0.2 and pip-tools => 5.0.0. #4215

• Updated vendored dependencies to latest versions for security and bug fixes:

  • requirementslib 1.5.8 => 1.5.9
  • vistir 0.5.0 => 0.5.1
  • jinja2 2.11.1 => 2.11.2
  • click 7.1.1 => 7.1.2
  • dateutil (none) => 2.8.1
  • backports.functools_lru_cache 1.5.0 => 1.6.1
  • enum34 1.1.6 => 1.1.10
  • toml 0.10.0 => 0.10.1
  • importlib_resources 1.4.0 => 1.5.0 #4226

• Changed attrs import path in vendored dependencies to always import from pipenv.vendor. #4267

Improved Documentation

• Added documenation about variable expansion in Pipfile entries. #2317
• Consolidate all contributing docs in the rst file #3120
• Update the out-dated manual page. #3246
• Move CLI docs to its own page. #3346
• Replace (non-existant) video on docs index.rst with equivalent gif. #3499
• Clarify wording in Basic Usage example on using double quotes to escape shell redirection #3522
• Ensure docs show navigation on small-screen devices #3527
• Added a link to the TOML Spec under General Recommendations & Version Control to clarify how Pipfiles should be written. #3629
• Updated the documentation with the new pytest entrypoint. #3759
• Fix link to GIF in README.md demonstrating Pipenv’s usage, and add descriptive alt text. #3911
• Added a line describing potential issues in fancy extension. #3912
• Documental description of how Pipfile works and association with Pipenv. #3913
• Clarify the proper value of python_version and python_full_version. #3914
• Write description for –deploy extension and few extensions differences. #3915
• More documentation for .env files #4100
• Updated documentation to point to working links. #4137
• Replace docs.pipenv.org with pipenv.pypa.io #4167
• Added functionality to check spelling in documentation and cleaned up existing typographical issues. #4209

2018.11.26 (2018-11-26)

Bug Fixes

• Environment variables are expanded correctly before running scripts on POSIX. #3178
• Pipenv will no longer disable user-mode installation when the --system flag is passed in. #3222
• Fixed an issue with attempting to render unicode output in non-unicode locales. #3223
• Fixed a bug which could cause failures to occur when parsing python entries from global pyenv version files. #3224
• Fixed an issue which prevented the parsing of named extras sections from certain setup.py files. #3230
• Correctly detect the virtualenv location inside an activated virtualenv. #3231
• Fixed a bug which caused spinner frames to be written to standard output during locking operations which could cause redirection pipes to fail. #3239
• Fixed a bug that editable packages can’t be uninstalled correctly. #3240
• Corrected an issue with installation timeouts which caused dependency resolution to fail for longer duration resolution steps. #3244
• Adding normal pep 508 compatible markers is now fully functional when using VCS dependencies. #3249
• Updated requirementslib and pythonfinder for multiple bug fixes. #3254
• Pipenv will now ignore hashes when installing with --skip-lock. #3255
• Fixed an issue where pipenv could crash when multiple pipenv processes attempted to create the same directory. #3257
• Fixed an issue which sometimes prevented successful creation of a project Pipfile. #3260
• pipenv install will now unset the PYTHONHOME environment variable when not combined with --system. #3261
• Pipenv will ensure that warnings do not interfere with the resolution process by suppressing warnings’ usage of standard output and writing to standard error instead. #3273
• Fixed an issue which prevented variables from the environment, such as PIPENV_DEV or PIPENV_SYSTEM, from being parsed and implemented correctly. #3278
• Clear pythonfinder cache after Python install. #3287
• Fixed a race condition in hash resolution for dependencies for certain dependencies with missing cache entries or fresh Pipenv installs. #3289
• Pipenv will now respect top-level pins over VCS dependency locks. #3296

Vendored Libraries

• Update vendored dependencies to resolve resolution output parsing and python finding:

  • pythonfinder 1.1.9 -> 1.1.10
  • requirementslib 1.3.1 -> 1.3.3
  • vistir 0.2.3 -> 0.2.5 #3280

2018.11.14 (2018-11-14)

Features & Improvements

• Improved exceptions and error handling on failures. #1977
• Added persistent settings for all CLI flags via PIPENV_{FLAG_NAME} environment variables by enabling auto_envvar_prefix=PIPENV in click (implements PEEP-0002). #2200
• Added improved messaging about available but skipped updates due to dependency conflicts when running pipenv update --outdated. #2411
• Added environment variable PIPENV_PYUP_API_KEY to add ability to override the bundled PyUP.io API key. #2825
• Added additional output to pipenv update --outdated to indicate that the operation succeeded and all packages were already up to date. #2828
• Updated crayons patch to enable colors on native powershell but swap native blue for magenta. #3020
• Added support for --bare to pipenv clean, and fixed pipenv sync --bare to actually reduce output. #3041
• Added windows-compatible spinner via upgraded vistir dependency. #3089
• • Added support for python installations managed by asdf. #3096
• Improved runtime performance of no-op commands such as pipenv --venv by around 2/3. #3158
• Do not show error but success for running pipenv uninstall --all in a fresh virtual environment. #3170
• Improved asynchronous installation and error handling via queued subprocess parallelization. #3217

Bug Fixes

• Remote non-PyPI artifacts and local wheels and artifacts will now include their own hashes rather than including hashes from PyPI. #2394
• Non-ascii characters will now be handled correctly when parsed by pipenv’s ToML parsers. #2737
• Updated pipenv uninstall to respect the --skip-lock argument. #2848
• Fixed a bug which caused uninstallation to sometimes fail to successfully remove packages from Pipfiles with comments on preceding or following lines. #2885, #3099
• Pipenv will no longer fail when encountering python versions on Windows that have been uninstalled. #2983
• Fixed unnecessary extras are added when translating markers #3026
• Fixed a virtualenv creation issue which could cause new virtualenvs to inadvertently attempt to read and write to global site packages. #3047
• Fixed an issue with virtualenv path derivation which could cause errors, particularly for users on WSL bash. #3055
• Fixed a bug which caused Unexpected EOF errors to be thrown when pip was waiting for input from users who had put login credentials in environment variables. #3088
• Fixed a bug in requirementslib which prevented successful installation from mercurial repositories. #3090
• Fixed random resource warnings when using pyenv or any other subprocess calls. #3094
• • Fixed a bug which sometimes prevented cloning and parsing mercurial requirements. #3096
• Fixed an issue in delegator.py related to subprocess calls when using PopenSpawn to stream output, which sometimes threw unexpected EOF errors. #3102, #3114, #3117
• Fix the path casing issue that makes pipenv clean fail on Windows #3104
• Pipenv will avoid leaving build artifacts in the current working directory. #3106
• Fixed issues with broken subprocess calls leaking resource handles and causing random and sporadic failures. #3109
• Fixed an issue which caused pipenv clean to sometimes clean packages from the base site-packages folder or fail entirely. #3113
• Updated pythonfinder to correct an issue with unnesting of nested paths when searching for python versions. #3121
• Added additional logic for ignoring and replacing non-ascii characters when formatting console output on non-UTF-8 systems. #3131
• Fix virtual environment discovery when PIPENV_VENV_IN_PROJECT is set, but the in-project .venv is a file. #3134
• Hashes for remote and local non-PyPI artifacts will now be included in Pipfile.lock during resolution. #3145
• Fix project path hashing logic in purpose to prevent collisions of virtual environments. #3151
• Fix package installation when the virtual environment path contains parentheses. #3158
• Azure Pipelines YAML files are updated to use the latest syntax and product name. #3164
• Fixed new spinner success message to write only one success message during resolution. #3183
• Pipenv will now correctly respect the --pre option when used with pipenv install. #3185
• Fix a bug where exception is raised when run pipenv graph in a project without created virtualenv #3201
• When sources are missing names, names will now be derived from the supplied URL. #3216

Vendored Libraries

• Updated pythonfinder to correct an issue with unnesting of nested paths when searching for python versions. #3061, #3121

• Updated vendored dependencies:

  • certifi 2018.08.24 => 2018.10.15
  • urllib3 1.23 => 1.24
  • requests 2.19.1 => 2.20.0
  • shellingham ``1.2.6 => 1.2.7
  • tomlkit 0.4.4. => 0.4.6
  • vistir 0.1.6 => 0.1.8
  • pythonfinder 0.1.2 => 0.1.3
  • requirementslib 1.1.9 => 1.1.10
  • backports.functools_lru_cache 1.5.0 (new)
  • cursor 1.2.0 (new) #3089

• Updated vendored dependencies:

  • requests 2.19.1 => 2.20.1
  • tomlkit 0.4.46 => 0.5.2
  • vistir 0.1.6 => 0.2.4
  • pythonfinder 1.1.2 => 1.1.8
  • requirementslib 1.1.10 => 1.3.0 #3096

• Switch to tomlkit for parsing and writing. Drop prettytoml and contoml from vendors. #3191
• Updated requirementslib to aid in resolution of local and remote archives. #3196

Improved Documentation

• Expanded development and testing documentation for contributors to get started. #3074

2018.10.13 (2018-10-13)

Bug Fixes

• Fixed a bug in pipenv clean which caused global packages to sometimes be inadvertently targeted for cleanup. #2849
• Fix broken backport imports for vendored vistir. #2950, #2955, #2961
• Fixed a bug with importing local vendored dependencies when running pipenv graph. #2952
• Fixed a bug which caused executable discovery to fail when running inside a virtualenv. #2957
• Fix parsing of outline tables. #2971
• Fixed a bug which caused verify_ssl to fail to drop through to pip install correctly as trusted-host. #2979
• Fixed a bug which caused canonicalized package names to fail to resolve against PyPI. #2989
• Enhanced CI detection to detect Azure Devops builds. #2993
• Fixed a bug which prevented installing pinned versions which used redirection symbols from the command line. #2998
• Fixed a bug which prevented installing the local directory in non-editable mode. #3005

Vendored Libraries

• Updated requirementslib to version 1.1.9. #2989
• Upgraded pythonfinder => 1.1.1 and vistir => 0.1.7. #3007

2018.10.9 (2018-10-09)

Features & Improvements

• Added environment variables PIPENV_VERBOSE and PIPENV_QUIET to control output verbosity without needing to pass options. #2527
• Updated test-PyPI add-on to better support json-API access (forward compatibility). Improved testing process for new contributors. #2568
• Greatly enhanced python discovery functionality:
  • Added pep514 (windows launcher/finder) support for python discovery.
  • Introduced architecture discovery for python installations which support different architectures. #2582
• Added support for pipenv shell on msys and cygwin/mingw/git bash for Windows. #2641
• Enhanced resolution of editable and VCS dependencies. #2643
• Deduplicate and refactor CLI to use stateful arguments and object passing. See this issue for reference. #2814

Behavior Changes

• Virtual environment activation for run is revised to improve interpolation with other Python discovery tools. #2503
• Improve terminal coloring to display better in Powershell. #2511
• Invoke virtualenv directly for virtual environment creation, instead of depending on pew. #2518
• pipenv --help will now include short help descriptions. #2542
• Add COMSPEC to fallback option (along with SHELL and PYENV_SHELL) if shell detection fails, improving robustness on Windows. #2651
• Fallback to shell mode if run fails with Windows error 193 to handle non-executable commands. This should improve usability on Windows, where some users run non-executable files without specifying a command, relying on Windows file association to choose the current command. #2718

Bug Fixes

• Fixed a bug which prevented installation of editable requirements using ssh:// style URLs #1393

• VCS Refs for locked local editable dependencies will now update appropriately to the latest hash when running pipenv update. #1690

• .tar.gz and .zip artifacts will now have dependencies installed even when they are missing from the Lockfile. #2173

• The command line parser will now handle multiple -e/--editable dependencies properly via click’s option parser to help mitigate future parsing issues. #2279

• Fixed the ability of pipenv to parse dependency_links from setup.py when PIP_PROCESS_DEPENDENCY_LINKS is enabled. #2434

• Fixed a bug which could cause -i/--index arguments to sometimes be incorrectly picked up in packages. This is now handled in the command line parser. #2494

• Fixed non-deterministic resolution issues related to changes to the internal package finder in pip 10. #2499, #2529, #2589, #2666, #2767, #2785, #2795, #2801, #2824, #2862, #2879, #2894, #2933

• Fix subshell invocation on Windows for Python 2. #2515

• Fixed a bug which sometimes caused pipenv to throw a TypeError or to run into encoding issues when writing a Lockfile on python 2. #2561

• Improve quoting logic for pipenv run so it works better with Windows built-in commands. #2563

• Fixed a bug related to parsing VCS requirements with both extras and subdirectory fragments. Corrected an issue in the requirementslib parser which led to some markers being discarded rather than evaluated. #2564

• Fixed multiple issues with finding the correct system python locations. #2582

• Catch JSON decoding error to prevent exception when the lock file is of invalid format. #2607

• Fixed a rare bug which could sometimes cause errors when installing packages with custom sources. #2610

• Update requirementslib to fix a bug which could raise an UnboundLocalError when parsing malformed VCS URIs. #2617

• Fixed an issue which prevented passing multiple --ignore parameters to pipenv check. #2632

• Fixed a bug which caused attempted hashing of ssh:// style URIs which could cause failures during installation of private ssh repositories. - Corrected path conversion issues which caused certain editable VCS paths to be converted to ssh:// URIs improperly. #2639

• Fixed a bug which caused paths to be formatted incorrectly when using pipenv shell in bash for windows. #2641

• Dependency links to private repositories defined via ssh:// schemes will now install correctly and skip hashing as long as PIP_PROCESS_DEPENDENCY_LINKS=1. #2643

• Fixed a bug which sometimes caused pipenv to parse the trusted_host argument to pip incorrectly when parsing source URLs which specify verify_ssl = false. #2656

• Prevent crashing when a virtual environment in WORKON_HOME is faulty. #2676

• Fixed virtualenv creation failure when a .venv file is present in the project root. #2680

• Fixed a bug which could cause the -e/--editable argument on a dependency to be accidentally parsed as a dependency itself. #2714

• Correctly pass verbose and debug flags to the resolver subprocess so it generates appropriate output. This also resolves a bug introduced by the fix to #2527. #2732

• All markers are now included in pipenv lock --requirements output. #2748

• Fixed a bug in marker resolution which could cause duplicate and non-deterministic markers. #2760

• Fixed a bug in the dependency resolver which caused regular issues when handling setup.py based dependency resolution. #2766

• Updated vendored dependencies:

  • pip-tools (updated and patched to latest w/ pip 18.0 compatibility)
  • pip 10.0.1 => 18.0
  • click 6.7 => 7.0
  • toml 0.9.4 => 0.10.0
  • pyparsing 2.2.0 => 2.2.2
  • delegator 0.1.0 => 0.1.1
  • attrs 18.1.0 => 18.2.0
  • distlib 0.2.7 => 0.2.8
  • packaging 17.1.0 => 18.0
  • passa 0.2.0 => 0.3.1
  • pip_shims 0.1.2 => 0.3.1
  • plette 0.1.1 => 0.2.2
  • pythonfinder 1.0.2 => 1.1.0
  • pytoml 0.1.18 => 0.1.19
  • requirementslib 1.1.16 => 1.1.17
  • shellingham 1.2.4 => 1.2.6
  • tomlkit 0.4.2 => 0.4.4
  • vistir 0.1.4 => 0.1.6 #2802,

  #2867, #2880

• Fixed a bug where pipenv crashes when the WORKON_HOME directory does not exist. #2877

• Fixed pip is not loaded from pipenv’s patched one but the system one #2912

• Fixed various bugs related to pip 18.1 release which prevented locking, installation, and syncing, and dumping to a requirements.txt file. #2924

Vendored Libraries

• Pew is no longer vendored. Entry point pewtwo, packages pipenv.pew and pipenv.patched.pew are removed. #2521

• Update pythonfinder to major release 1.0.0 for integration. #2582

• Update requirementslib to fix a bug which could raise an UnboundLocalError when parsing malformed VCS URIs. #2617

• • Vendored new libraries vistir and pip-shims, tomlkit, modutil, and plette.
  • Update vendored libraries: - scandir to 1.9.0 - click-completion to 0.4.1 - semver to 2.8.1 - shellingham to 1.2.4 - pytoml to 0.1.18 - certifi to 2018.8.24 - ptyprocess to 0.6.0 - requirementslib to 1.1.5 - pythonfinder to 1.0.2 - pipdeptree to 0.13.0 - python-dotenv to 0.9.1 #2639

• Updated vendored dependencies:

  • pip-tools (updated and patched to latest w/ pip 18.0 compatibility)
  • pip 10.0.1 => 18.0
  • click 6.7 => 7.0
  • toml 0.9.4 => 0.10.0
  • pyparsing 2.2.0 => 2.2.2
  • delegator 0.1.0 => 0.1.1
  • attrs 18.1.0 => 18.2.0
  • distlib 0.2.7 => 0.2.8
  • packaging 17.1.0 => 18.0
  • passa 0.2.0 => 0.3.1
  • pip_shims 0.1.2 => 0.3.1
  • plette 0.1.1 => 0.2.2
  • pythonfinder 1.0.2 => 1.1.0
  • pytoml 0.1.18 => 0.1.19
  • requirementslib 1.1.16 => 1.1.17
  • shellingham 1.2.4 => 1.2.6
  • tomlkit 0.4.2 => 0.4.4
  • vistir 0.1.4 => 0.1.6 #2902,

  #2935

Improved Documentation

• Simplified the test configuration process. #2568
• Updated documentation to use working fortune cookie add-on. #2644
• Added additional information about troubleshooting pipenv shell by using the the $PIPENV_SHELL environment variable. #2671
• Added a link to PEP-440 version specifiers in the documentation for additional detail. #2674
• Added simple example to README.md for installing from git. #2685
• Stopped recommending –system for Docker contexts. #2762
• Fixed the example url for doing “pipenv install -e some-repository-url#egg=something”, it was missing the “egg=” in the fragment identifier. #2792
• Fixed link to the “be cordial” essay in the contribution documentation. #2793
• Clarify pipenv install documentation #2844
• Replace reference to uservoice with PEEP-000 #2909

2018.7.1 (2018-07-01)

Features & Improvements

• All calls to pipenv shell are now implemented from the ground up using shellingham, a custom library which was purpose built to handle edge cases and shell detection. #2371
• Added support for python 3.7 via a few small compatibility / bug fixes. #2427, #2434, #2436
• Added new flag pipenv --support to replace the diagnostic command python -m pipenv.help. #2477, #2478
• Improved import times and CLI run times with minor tweaks. #2485

Bug Fixes

• Fixed an ongoing bug which sometimes resolved incompatible versions into the project Lockfile. #1901
• Fixed a bug which caused errors when creating virtualenvs which contained leading dash characters. #2415
• Fixed a logic error which caused --deploy --system to overwrite editable vcs packages in the Pipfile before installing, which caused any installation to fail by default. #2417
• Updated requirementslib to fix an issue with properly quoting markers in VCS requirements. #2419
• Installed new vendored jinja2 templates for click-completion which were causing template errors for users with completion enabled. #2422
• Added support for python 3.7 via a few small compatibility / bug fixes. #2427
• Fixed an issue reading package names from setup.py files in projects which imported utilities such as versioneer. #2433
• Pipenv will now ensure that its internal package names registry files are written with unicode strings. #2450
• Fixed a bug causing requirements input as relative paths to be output as absolute paths or URIs. Fixed a bug affecting normalization of git+git@host URLs. #2453
• Pipenv will now always use pathlib2 for Path based filesystem interactions by default on python<3.5. #2454
• Fixed a bug which prevented passing proxy PyPI indexes set with --pypi-mirror from being passed to pip during virtualenv creation, which could cause the creation to freeze in some cases. #2462
• Using the python -m pipenv.help command will now use proper encoding for the host filesystem to avoid encoding issues. #2466
• The new jinja2 templates for click_completion will now be included in pipenv source distributions. #2479
• Resolved a long-standing issue with re-using previously generated InstallRequirement objects for resolution which could cause PKG-INFO file information to be deleted, raising a TypeError. #2480
• Resolved an issue parsing usernames from private PyPI URIs in Pipfiles by updating requirementslib. #2484

Vendored Libraries

• All calls to pipenv shell are now implemented from the ground up using shellingham, a custom library which was purpose built to handle edge cases and shell detection. #2371
• Updated requirementslib to fix an issue with properly quoting markers in VCS requirements. #2419
• Installed new vendored jinja2 templates for click-completion which were causing template errors for users with completion enabled. #2422
• Add patch to prettytoml to support Python 3.7. #2426
• Patched prettytoml.AbstractTable._enumerate_items to handle StopIteration errors in preparation of release of python 3.7. #2427
• Fixed an issue reading package names from setup.py files in projects which imported utilities such as versioneer. #2433
• Updated requirementslib to version 1.0.9 #2453
• Unraveled a lot of old, unnecessary patches to pip-tools which were causing non-deterministic resolution errors. #2480
• Resolved an issue parsing usernames from private PyPI URIs in Pipfiles by updating requirementslib. #2484

Improved Documentation

• Added instructions for installing using Fedora’s official repositories. #2404

2018.6.25 (2018-06-25)

Features & Improvements

• Pipenv-created virtualenvs will now be associated with a .project folder (features can be implemented on top of this later or users may choose to use pipenv-pipes to take full advantage of this.) #1861
• Virtualenv names will now appear in prompts for most Windows users. #2167
• Added support for cmder shell paths with spaces. #2168
• Added nested JSON output to the pipenv graph command. #2199
• Dropped vendored pip 9 and vendored, patched, and migrated to pip 10. Updated patched piptools version. #2255
• PyPI mirror URLs can now be set to override instances of PyPI URLs by passing the --pypi-mirror argument from the command line or setting the PIPENV_PYPI_MIRROR environment variable. #2281
• Virtualenv activation lines will now avoid being written to some shell history files. #2287
• Pipenv will now only search for requirements.txt files when creating new projects, and during that time only if the user doesn’t specify packages to pass in. #2309
• Added support for mounted drives via UNC paths. #2331
• Added support for Windows Subsystem for Linux bash shell detection. #2363
• Pipenv will now generate hashes much more quickly by resolving them in a single pass during locking. #2384
• pipenv run will now avoid spawning additional COMSPEC instances to run commands in when possible. #2385
• Massive internal improvements to requirements parsing codebase, resolver, and error messaging. #2388
• pipenv check now may take multiple of the additional argument --ignore which takes a parameter cve_id for the purpose of ignoring specific CVEs. #2408

Behavior Changes

• Pipenv will now parse & capitalize platform_python_implementation markers .. warning:: This could cause an issue if you have an out of date Pipfile which lower-cases the comparison value (e.g. cpython instead of CPython). #2123
• Pipenv will now only search for requirements.txt files when creating new projects, and during that time only if the user doesn’t specify packages to pass in. #2309

Bug Fixes

• Massive internal improvements to requirements parsing codebase, resolver, and error messaging. #1962, #2186, #2263, #2312
• Pipenv will now parse & capitalize platform_python_implementation markers. #2123
• Fixed a bug with parsing and grouping old-style setup.py extras during resolution #2142
• Fixed a bug causing pipenv graph to throw unhelpful exceptions when running against empty or non-existent environments. #2161
• Fixed a bug which caused --system to incorrectly abort when users were in a virtualenv. #2181
• Removed vendored cacert.pem which could cause issues for some users with custom certificate settings. #2193
• Fixed a regression which led to direct invocations of virtualenv, rather than calling it by module. #2198
• Locking will now pin the correct VCS ref during pipenv update runs. Running pipenv update with a new vcs ref specified in the Pipfile will now properly obtain, resolve, and install the specified dependency at the specified ref. #2209
• pipenv clean will now correctly ignore comments from pip freeze when cleaning the environment. #2262
• Resolution bugs causing packages for incompatible python versions to be locked have been fixed. #2267
• Fixed a bug causing pipenv graph to fail to display sometimes. #2268
• Updated requirementslib to fix a bug in Pipfile parsing affecting relative path conversions. #2269
• Windows executable discovery now leverages os.pathext. #2298
• Fixed a bug which caused --deploy --system to inadvertently create a virtualenv before failing. #2301
• Fixed an issue which led to a failure to unquote special characters in file and wheel paths. #2302
• VCS dependencies are now manually obtained only if they do not match the requested ref. #2304
• Added error handling functionality to properly cope with single-digit Requires-Python metadata with no specifiers. #2377
• pipenv update will now always run the resolver and lock before ensuring dependencies are in sync with project Lockfile. #2379
• Resolved a bug in our patched resolvers which could cause nondeterministic resolution failures in certain conditions. Running pipenv install with no arguments in a project with only a Pipfile will now correctly lock first for dependency resolution before installing. #2384
• Patched python-dotenv to ensure that environment variables always get encoded to the filesystem encoding. #2386

Improved Documentation

• Update documentation wording to clarify Pipenv’s overall role in the packaging ecosystem. #2194
• Added contribution documentation and guidelines. #2205
• Added instructions for supervisord compatibility. #2215
• Fixed broken links to development philosophy and contribution documentation. #2248

Vendored Libraries

• Removed vendored cacert.pem which could cause issues for some users with custom certificate settings. #2193

• Dropped vendored pip 9 and vendored, patched, and migrated to pip 10. Updated patched piptools version. #2255

• Updated requirementslib to fix a bug in Pipfile parsing affecting relative path conversions. #2269

• Added custom shell detection library shellingham, a port of our changes to pew. #2363

• Patched python-dotenv to ensure that environment variables always get encoded to the filesystem encoding. #2386

• Updated vendored libraries. The following vendored libraries were updated:

  • distlib from version 0.2.6 to 0.2.7.
  • jinja2 from version 2.9.5 to 2.10.
  • pathlib2 from version 2.1.0 to 2.3.2.
  • parse from version 2.8.0 to 2.8.4.
  • pexpect from version 2.5.2 to 2.6.0.
  • requests from version 2.18.4 to 2.19.1.
  • idna from version 2.6 to 2.7.
  • certifi from version 2018.1.16 to 2018.4.16.
  • packaging from version 16.8 to 17.1.
  • six from version 1.10.0 to 1.11.0.
  • requirementslib from version 0.2.0 to 1.0.1.

  In addition, scandir was vendored and patched to avoid importing host system binaries when falling back to pathlib2. #2368

用户推荐语

David Gang—

这个包管理工具真的太好用了。我有生第一次知道了我安装了哪些依赖和哪些过渡依赖。再加上依赖的安装是确定性的，使得这个包管理工具成为人们的优先选择，就像cargo 。

Justin Myles Holmes—

终于出现了Pipenv这样的良好的抽象层，它占据你的大脑，而不仅仅是文件系统。

☤ Pipenv的特性

• 支持真正的 一致性构建 ，只需简单的指定 你想要什么。
• 从锁定的依赖中生成文件哈希值用来做校验。
• 在 pyenv 可用时，自动安装需要的Python版本。
• 通过搜索 Pipfile ，自动地递归查找项目根目录。
• 如果 Pipfile 不存在，自动为你生成一个。
• 在标准位置自动创建一个虚拟环境。
• Automatically adds/removes packages to a Pipfile when they are installed or uninstalled.
• 若探测到 .env 文件存在，自动加载它。

主要的命令有 install ， uninstall ，和用来生成 Pipfile.lock 的 lock 命令。这些命令可以取代 $ pip install , 以及人工管理虚拟环境(要激活一个虚拟环境，可以运行 $ pipenv shell )。

基本概念

• 如果虚拟环境不存在，会被自动创建。
• install 命令后面如果不带参数，则安装 [packages] 下面所有的包。
• 使用 $ pipenv --three 来指定用Python 3初始化虚拟环境。
• 使用 $ pipenv --two 来指定用Python 2初始化虚拟环境。
• 否则，和 virtualenv 一样，使用默认的Python版本。

其他命令

• graph 命令可以展示当前安装的包的依赖关系树。
• shell 命令会启动一个激活了虚拟环境的shell，在此shell中可以使用 exist 退出。
• run 命令可以在虚拟环境中运行一段给定的命令，并转发其他命令参数(比如： $ pipenv run python 或者 $ pipenv run pip freeze )。
• check 命令可以检查安全漏洞，以及当前环境是否满足PEP 508标签的要求。

进一步文档指南。

Pipenv的基本使用

这篇文档覆盖了Pipenv的一些基本特性。

☤ Pipfile与Pipfile.lock示例

Pipfiles contain information for the dependencies of the project, and supersedes the requirements.txt file used in most Python projects. You should add a Pipfile in the Git repository letting users who clone the repository know the only thing required would be installing Pipenv in the machine and typing pipenv install. Pipenv is a reference implementation for using Pipfile.

下面是一个简单的 Pipfile 示例以及对应的 Pipfile.lock 。

Pipfile示例

[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "*"


[dev-packages]
pytest = "*"

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"
        }
    }
}

☤ 一般推荐与版本控制

• 通常情况下，把 Pipfile 和 Pipfile.lock 都纳入版本控制。
• 当需要兼容多个Python版本时，请勿把 Pipfile.lock 纳入版本控制。
• 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. python_version should be in the format X.Y (or X) and python_full_version should be in X.Y.Z format.
• pipenv install 语法与 pip install 完全兼容，完整文档可见 这里 。
• Note that the Pipfile uses the TOML Spec.

☤ Pipenv工作流示例

克隆、创建一个项目仓库:

$ cd myproject

如果已经有一个Pipfile，从Pipfile安装:

$ pipenv install

或者，添加一个包到你的项目中:

$ pipenv install <package>

如果 Pipfile 不存在会创建一个。否则，它的内容会自动更新加入新的包。

接下来，激活Pipenv的终端:

$ pipenv shell
$ python --version

这会启动一个新的终端进程，可以通过 exit 来退出。

☤ Pipenv升级工作流示例

• 查看上游更新的内容: $ pipenv update --outdated。

• 升级包版本，有两种方法：

  1. 想要升级所有依赖包？只需要 $ pipenv update 。
  2. 想要一个个升级包？对每一个包 $ pipenv update <pkg> 。

☤ 从requirements.txt中导入

如果你运行 pipenv install 时只有一个 requirements.txt，pipenv会自动将文件内容导入进来为你创建一个 Pipfile 。

你也可以指定 $ pipenv install -r path/to/requirements.txt 导入某个requirements文件。

如果你的requirements文件中锚定了版本号，你可能需要编辑新的 Pipfile 去掉它们，让 pipenv 去管理版本。如果你需要保持 Pipfile.lock 中锚定的版本不变，运行 pipenv lock --keep-outdated 。别忘了立刻 更新 ！

☤ 指定包的版本

你可以使用 语义版本规范 指定包的版本(如： major.minor.micro)。

例如，安装requests你可以用：:

$ pipenv install requests~=1.2

Pipenv会安装 1.2 版本以及后续所有的次版本更新，但不包括 2.0 。

这会自动更新你的 Pipfile 一反映最新变化。

一般来说，Pipenv和pip使用相同的版本标识。但注意到 PEP 440 ，你不能使用包含连字符与加号的版本。

要用包含与不包含的版本比较你可以用：:

$ 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

注解

高度推荐用双引号包裹包版本标识(如 "requests>2.19")，这是为了避免在基于Unix的操作系统中出现 输入输出重定向问题 。

~= 比 == 标识符更加推荐，因为后者会使得pipenv无法更新包：:

$ pipenv install "requests~=2.2"  # locks the major version of the package (this is equivalent to using ==2.*)

要防止安装包的某个版本可以使用 != 标识符。

想要获得关于有效标识符和更加复杂的使用方法请参考 the relevant section of PEP-440 。

☤ 指定Python的版本

想要使用一个已有的Python版本创建虚拟环境，使用 --python VERSON 选项，类似这样：

使用Python 3:

$ pipenv --python 3

使用Python 3.6:

$ pipenv --python 3.6

使用Python 2.7.14:

$ pipenv --python 2.7.14

如果提供了Python版本，就像这样，Pipenv会自动扫描系统上和提供的版本匹配的Python。

如果 Pipfile 还未创建会自动创建一个，看起来的效果是这样:

[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true

[dev-packages]

[packages]

[requires]
python_version = "3.6"

注解

[requires] python_version = "3.6" 的加入说明你的应用需要这个版本的Python，以后在运行 pipenv install 时会自动使用这个 Pipfile (比如在另一台机器上)。如果不能满足，可以自己删除这一节。

如果你没有在命令行中指定Python的版本，那么会自动选择 [requires] 中的``python_full_version`` 或 python_version 。执行时候回退到当前系统的默认Python版本。

可修改依赖 (如 -e . )

你可以让Pipenv以可修改模式安装某个路径——通常用于开发Python包时，安装当前工作目录。

$ pipenv install --dev -e .

$ cat Pipfile
...
[dev-packages]
"e1839a8" = {path = ".", editable = true}
...

注解

所有次级依赖也会加到 Pipfile.lock 中。如果没有加 -e 选项次级依赖将 不 会加到 Pipfile.lock 中。

☤ 用Pipenv管理环境

用来管理你的pipenv环境的三个主要命令是 $ pipenv install ， $ pipenv uninstall ， 以及 $ pipenv lock 。

$ pipenv install

$ pipenv install 用于把包安装到pipenv虚拟环境及更新Pipfile。

与下面的形式的基本的安装命令一起:

$ pipenv install [package names]

用户可以提供这些额外的参数：

• --two —— 在使用Python 2的虚拟环境中进行安装。
• --three —— 在使用Python 3的虚拟环境中进行安装。
• --python —— 在使用给定Python解释器的虚拟环境中进行安装。

警告

上述的选项均不能同时使用。同时它们也是 破坏性的，会删除你当前的虚拟环境，然后替换成一个适当版本的环境。

注解

Pipenv创建的虚拟环境可能与你预期的有所不同。危险字符(比如 $`!*@" 和空格、换行、制表符)会被替换成下划线。此外，当前目录的全路径会被编码成哈希值并追加到虚拟环境名称中来确保名称唯一。

• --dev —— 同时安装 Pipfile 中 develop 与 default 里面的包。
• --system ——使用系统的 pip 命令而不是虚拟环境中的。
• --deploy — Make sure the packages are properly locked in Pipfile.lock, and abort if the lock file is out-of-date.
• --ignore-pipfile ——忽略 Pipfile 直接从 Pipfile.lock 中安装。
• --skip-lock ——忽略 Pipfile.lock，直接从 Pipfile 中安装。此外也不会更新 Pipfile.lock 以跟踪 Pipfile 的变化。

$ pipenv uninstall

$ pipenv uninstall 支持 pipenv install 中的全部参数，以及两个额外的选项， --all 和 --all-dev 。

• --all ——此参数会删除虚拟环境所有的包，但不改变Pipfile。
• --all-dev ——此参数会删除虚拟环境中所有的开发包，并从Pipfile中删除。

$ pipenv lock

$ pipenv lock 用来创建一个 Pipfile.lock ，其中指明了项目的 所有 依赖(及次级依赖)，它们的最新可以版本，与当前下载文件的哈希值。这确保了构建是可重复的，最重要是 确定性 的。

☤ 关于终端配置

作为子终端使用时，终端通常是未配置的，因此 $ pipenv shell --fancy 可能会出现不可预料的结果。如果是这样，尝试使用 $ pipenv shell ，它会使用「兼容模式」尝试启动一个未配置的子终端。

一个正确的终端配置仅在登录会话是设置类似 PATH 的环境变量，而不是在每次子终端启动时(因为通常配置成这样做)。在fish中，这类似于下面这样:

if status --is-login
    set -gx PATH /usr/local/bin $PATH
end

你应该在你的终端里也这样做，放在你的 ~/.profile or ~/.bashrc 或者其他合适的地方。

注解

终端以交互模式启动。这表示如果你的终端从某个文件读取交互模式的配置(如bash默认为交互模式寻找 ~/.bashrc 配置文件)，你需要修改(或创建)这个文件。

如果你在用 $ pipenv shell 时遇到问题，检查一下 PIPENV_SHELL 环境变量，它若存在则会被 $ pipenv shell 使用。具体可参考 ☤ Configuration With Environment Variables 。

☤ 关于版本控制系统依赖的注意事项

你可以用pipenv从git或其他版本控制系统安装依赖，使用的URL应遵循以下规则:

<vcs_type>+<scheme>://<location>/<user_or_organization>/<repository>@<branch_or_tag>#egg=<package_name>

仅有 @<branch_or_tag> 部分是可选的。当通过SSH连接git时，你可以用简短URL前缀 git+git@<location>:<user_or_organization>/<repository>@<branch_or_tag>#<package_name> ，在解析时会被转译为 git+ssh://git@<location> 。

注意， 强烈推荐 你用可修改模式安装任何版本控制系统依赖，即 pipenv install -e ，以确保每次解析依赖时在仓库的最新版本的基础上进行，并且正确包含所有已知依赖。

下面的例子演示了如何从git仓库 https://github.com/requests/requests.git 的 v2.20.1 标签，以 requests 作包名安装:

$ pipenv install -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests
Creating a Pipfile for this project...
Installing -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests...
[...snipped...]
Adding -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests to Pipfile's [packages]...
[...]

$ cat Pipfile
[packages]
requests = {git = "https://github.com/requests/requests.git", editable = true, ref = "v2.20.1"}

<vcs_type> 的有效值包括 git， bzr， svn 和 hg 。<scheme> 的有效值包括 http ， https ， ssh 和 file 。在特定情况下你也可以使用其他的前缀： svn 可以和 svn 组合使用， bzr 可以和 sftp 或 lp 组合使用。

可以到 这里 阅读更多pip对于版本控制系统支持的实现。更多关于其他版本控制系统依赖可选的选项，请参阅 Pipfile标准 。

☤ Pipfile.lock安全特性

Pipfile.lock 利用了 pip 中的一些很好的安全改进。默认情况下， Pipfile.lock 会生成所有已下载包的sha256哈希值。这使得 pip 在不安全网络情况下，保证你安装了你想要的包，或者从一个不信任的PyPI源下载依赖。

我们高度推荐将一个开放环境中的项目提升到生产环境来部署。你可以用 pipenv lock 来固化开发环境中的依赖，然后将生成的 Pipfile.lock 部署到所有生产环境，来达到可复制构建的效果。

注解

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.

Advanced Usage of Pipenv

This document covers some of Pipenv’s more glorious and advanced features.

☤ Caveats

• Dependencies of wheels provided in a Pipfile will not be captured by $ pipenv lock.
• There are some known issues with using private indexes, related to hashing. We’re actively working to solve this problem. You may have great luck with this, however.
• Installation is intended to be as deterministic as possible — use the --sequential flag to increase this, if experiencing issues.

☤ Specifying Package Indexes

If you’d like a specific package to be installed with a specific package index, you can do the following:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[[source]]
url = "http://pypi.home.kennethreitz.org/simple"
verify_ssl = false
name = "home"

[dev-packages]

[packages]
requests = {version="*", index="home"}
maya = {version="*", index="pypi"}
records = "*"

Very fancy.

☤ Using a PyPI Mirror

If you would like to override the default PyPI index URLs with the URL for a PyPI mirror, you can use the following:

$ pipenv install --pypi-mirror <mirror_url>

$ pipenv update --pypi-mirror <mirror_url>

$ pipenv sync --pypi-mirror <mirror_url>

$ pipenv lock --pypi-mirror <mirror_url>

$ pipenv uninstall --pypi-mirror <mirror_url>

Alternatively, you can set the PIPENV_PYPI_MIRROR environment variable.

☤ Injecting credentials into Pipfiles via environment variables

Pipenv will expand environment variables (if defined) in your Pipfile. Quite useful if you need to authenticate to a private PyPI:

[[source]]
url = "https://$USERNAME:${PASSWORD}@mypypi.example.com/simple"
verify_ssl = true
name = "pypi"

Luckily - pipenv will hash your Pipfile before expanding environment variables (and, helpfully, will substitute the environment variables again when you install from the lock file - so no need to commit any secrets! Woo!)

If your credentials contain a special character, surround the references to the environment variables with quotation marks. For example, if your password contain a double quotation mark, surround the password variable with single quotation marks. Otherwise, you may get a ValueError, "No closing quotation" error while installing dependencies.

[[source]]
url = "https://$USERNAME:'${PASSWORD}'@mypypi.example.com/simple"

☤ Specifying Basically Anything

If you’d like to specify that a specific package only be installed on certain systems, you can use PEP 508 specifiers to accomplish this.

Here’s an example Pipfile, which will only install pywinusb on Windows systems:

[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "*"
pywinusb = {version = "*", sys_platform = "== 'win32'"}

Voilà!

Here’s a more complex example:

[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true

[packages]
unittest2 = {version = ">=1.0,<3.0", markers="python_version < '2.7.9' or (python_version >= '3.0' and python_version < '3.4')"}

Magic. Pure, unadulterated magic.

☤ Using pipenv for Deployments

You may want to use pipenv as part of a deployment process.

You can enforce that your Pipfile.lock is up to date using the --deploy flag:

$ pipenv install --deploy

This will fail a build if the Pipfile.lock is out–of–date, instead of generating a new one.

Or you can install packages exactly as specified in Pipfile.lock using the sync command:

$ pipenv sync

注解

pipenv install --ignore-pipfile is nearly equivalent to pipenv sync, but pipenv sync will never attempt to re-lock your dependencies as it is considered an atomic operation. pipenv install by default does attempt to re-lock unless using the --deploy flag.

Deploying System Dependencies

You can tell Pipenv to install a Pipfile’s contents into its parent system with the --system flag:

$ pipenv install --system

This is useful for managing the system Python, and deployment infrastructure (e.g. Heroku does this).

☤ Pipenv and Other Python Distributions

To use Pipenv with a third-party Python distribution (e.g. Anaconda), you simply provide the path to the Python binary:

$ pipenv install --python=/path/to/python

Anaconda uses Conda to manage packages. To reuse Conda–installed Python packages, use the --site-packages flag:

$ pipenv --python=/path/to/python --site-packages

☤ Generating a requirements.txt

You can convert a Pipfile and Pipfile.lock into a requirements.txt file very easily, and get all the benefits of extras and other goodies we have included.

Let’s take this Pipfile:

[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true

[packages]
requests = {version="*"}

[dev-packages]
pytest = {version="*"}

And generate a set of requirements out of it with only the default dependencies:

$ pipenv lock -r
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
idna==2.6
urllib3==1.22

As with other commands, passing --dev will include both the default and development dependencies:

$ pipenv lock -r --dev
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
idna==2.6
urllib3==1.22
py==1.4.34
pytest==3.2.3

Finally, if you wish to generate a requirements file with only the development requirements you can do that too, using the --dev-only flag:

$ pipenv lock -r --dev-only
py==1.4.34
pytest==3.2.3

The locked requirements are written to stdout, with shell output redirection used to write them to a file:

$ pipenv lock -r > requirements.txt
$ pipenv lock -r --dev-only > dev-requirements.txt
$ cat requirements.txt
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
idna==2.6
urllib3==1.22
$ cat dev-requirements.txt
py==1.4.34
pytest==3.2.3

☤ Detection of Security Vulnerabilities

Pipenv includes the safety package, and will use it to scan your dependency graph for known security vulnerabilities!

Example:

$ cat Pipfile
[packages]
django = "==1.10.1"

$ pipenv check
Checking PEP 508 requirements…
Passed!
Checking installed package safety…

33075: django >=1.10,<1.10.3 resolved (1.10.1 installed)!
Django before 1.8.x before 1.8.16, 1.9.x before 1.9.11, and 1.10.x before 1.10.3, when settings.DEBUG is True, allow remote attackers to conduct DNS rebinding attacks by leveraging failure to validate the HTTP Host header against settings.ALLOWED_HOSTS.

33076: django >=1.10,<1.10.3 resolved (1.10.1 installed)!
Django 1.8.x before 1.8.16, 1.9.x before 1.9.11, and 1.10.x before 1.10.3 use a hardcoded password for a temporary database user created when running tests with an Oracle database, which makes it easier for remote attackers to obtain access to the database server by leveraging failure to manually specify a password in the database settings TEST dictionary.

33300: django >=1.10,<1.10.7 resolved (1.10.1 installed)!
CVE-2017-7233: Open redirect and possible XSS attack via user-supplied numeric redirect URLs
============================================================================================

Django relies on user input in some cases  (e.g.
:func:`django.contrib.auth.views.login` and :doc:`i18n </topics/i18n/index>`)
to redirect the user to an "on success" URL. The security check for these
redirects (namely ``django.utils.http.is_safe_url()``) considered some numeric
URLs (e.g. ``http:999999999``) "safe" when they shouldn't be.

Also, if a developer relies on ``is_safe_url()`` to provide safe redirect
targets and puts such a URL into a link, they could suffer from an XSS attack.

CVE-2017-7234: Open redirect vulnerability in ``django.views.static.serve()``
=============================================================================

A maliciously crafted URL to a Django site using the
:func:`~django.views.static.serve` view could redirect to any other domain. The
view no longer does any redirects as they don't provide any known, useful
functionality.

Note, however, that this view has always carried a warning that it is not
hardened for production use and should be used only as a development aid.

✨🍰✨

注解

Each month, PyUp.io updates the safety database of insecure Python packages and makes it available to the community for free. Pipenv makes an API call to retrieve those results and use them each time you run pipenv check to show you vulnerable dependencies.

For more up-to-date vulnerability data, you may also use your own safety API key by setting the environment variable PIPENV_PYUP_API_KEY.

☤ Community Integrations

There are a range of community-maintained plugins and extensions available for a range of editors and IDEs, as well as different products which integrate with Pipenv projects:

• Heroku (Cloud Hosting)
• Platform.sh (Cloud Hosting)
• PyUp (Security Notification)
• Emacs (Editor Integration)
• Fish Shell (Automatic $ pipenv shell!)
• VS Code (Editor Integration)
• PyCharm (Editor Integration)

Works in progress:

• Sublime Text (Editor Integration)
• Mysterious upcoming Google Cloud product (Cloud Hosting)

☤ Open a Module in Your Editor

Pipenv allows you to open any Python module that is installed (including ones in your codebase), with the $ pipenv open command:

$ pipenv install -e git+https://github.com/kennethreitz/background.git#egg=background
Installing -e git+https://github.com/kennethreitz/background.git#egg=background…
...
Updated Pipfile.lock!

$ pipenv open background
Opening '/Users/kennethreitz/.local/share/virtualenvs/hmm-mGOawwm_/src/background/background.py' in your EDITOR.

This allows you to easily read the code you’re consuming, instead of looking it up on GitHub.

注解

The standard EDITOR environment variable is used for this. If you’re using VS Code, for example, you’ll want to export EDITOR=code (if you’re on macOS you will want to install the command on to your PATH first).

☤ Automatic Python Installation

If you have pyenv installed and configured, Pipenv will automatically ask you if you want to install a required version of Python if you don’t already have it available.

This is a very fancy feature, and we’re very proud of it:

$ cat Pipfile
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true

[dev-packages]

[packages]
requests = "*"

[requires]
python_version = "3.6"

$ pipenv install
Warning: Python 3.6 was not found on your system…
Would you like us to install latest CPython 3.6 with pyenv? [Y/n]: y
Installing CPython 3.6.2 with pyenv (this may take a few minutes)…
...
Making Python installation global…
Creating a virtualenv for this project…
Using /Users/kennethreitz/.pyenv/shims/python3 to create virtualenv…
...
No package provided, installing all dependencies.
...
Installing dependencies from Pipfile.lock…
🐍   ❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒❒ 5/5 — 00:00:03
To activate this project's virtualenv, run the following:
 $ pipenv shell

Pipenv automatically honors both the python_full_version and python_version PEP 508 specifiers.

💫✨🍰✨💫

☤ Automatic Loading of .env

If a .env file is present in your project, $ pipenv shell and $ pipenv run will automatically load it, for you:

$ cat .env
HELLO=WORLD⏎

$ pipenv run python
Loading .env environment variables…
Python 2.7.13 (default, Jul 18 2017, 09:17:00)
[GCC 4.2.1 Compatible Apple LLVM 8.1.0 (clang-802.0.42)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ['HELLO']
'WORLD'

Shell like variable expansion is available in .env files using ${VARNAME} syntax.:

$ cat .env
CONFIG_PATH=${HOME}/.config/foo

$ pipenv run python
Loading .env environment variables…
Python 3.7.6 (default, Dec 19 2019, 22:52:49)
[GCC 9.2.1 20190827 (Red Hat 9.2.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ['CONFIG_PATH']
'/home/kennethreitz/.config/foo'

This is very useful for keeping production credentials out of your codebase. We do not recommend committing .env files into source control!

If your .env file is located in a different path or has a different name you may set the PIPENV_DOTENV_LOCATION environment variable:

$ PIPENV_DOTENV_LOCATION=/path/to/.env pipenv shell

To prevent pipenv from loading the .env file, set the PIPENV_DONT_LOAD_ENV environment variable:

$ PIPENV_DONT_LOAD_ENV=1 pipenv shell

See theskumar/python-dotenv for more information on .env files.

☤ Custom Script Shortcuts

Pipenv supports creating custom shortcuts in the (optional) [scripts] section of your Pipfile.

You can then run pipenv run <shortcut name> in your terminal to run the command in the context of your pipenv virtual environment even if you have not activated the pipenv shell first.

For example, in your Pipfile:

[scripts]
printspam = "python -c \"print('I am a silly example, no one would need to do this')\""

And then in your terminal:

$ pipenv run printspam
I am a silly example, no one would need to do this

Commands that expect arguments will also work. For example:

[scripts]
echospam = "echo I am really a very silly example"

$ pipenv run echospam "indeed"
I am really a very silly example indeed

☤ Support for Environment Variables

Pipenv supports the usage of environment variables in place of authentication fragments in your Pipfile. These will only be parsed if they are present in the [[source]] section. For example:

[[source]]
url = "https://${PYPI_USERNAME}:${PYPI_PASSWORD}@my_private_repo.example.com/simple"
verify_ssl = true
name = "pypi"

[dev-packages]

[packages]
requests = {version="*", index="home"}
maya = {version="*", index="pypi"}
records = "*"

Environment variables may be specified as ${MY_ENVAR} or $MY_ENVAR.

On Windows, %MY_ENVAR% is supported in addition to ${MY_ENVAR} or $MY_ENVAR.

☤ 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.

If you’d like to set these environment variables on a per-project basis, I recommend utilizing the fantastic direnv project, in order to do so.

Also note that pip itself supports environment variables, if you need additional customization.

For example:

$ PIP_INSTALL_OPTION="-- -DCMAKE_BUILD_TYPE=Release" pipenv install -e .

☤ Custom Virtual Environment Location

Pipenv automatically honors 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

In addition, you can also have Pipenv stick the virtualenv in project/.venv by setting the PIPENV_VENV_IN_PROJECT environment variable.

☤ Testing Projects

Pipenv is being used in projects like Requests for declaring development dependencies and running the test suite.

We have currently tested deployments with both Travis-CI and tox with success.

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.7-dev"

# 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 pytest 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]
deps = pipenv
commands=
    pipenv install --dev
    pipenv run pytest tests

[testenv:flake8-py3]
basepython = python3.4
commands=
    pipenv install --dev
    pipenv run flake8 --version
    pipenv run flake8 setup.py docs project test

Pipenv will automatically use the virtualenv provided by tox. If pipenv install --dev installs e.g. pytest, then installed command pytest will be present in given virtualenv and can be called directly by pytest tests instead of pipenv run pytest tests.

You might also want to add --ignore-pipfile to pipenv install, as to not accidentally modify the lock-file on each test run. This causes Pipenv to ignore changes to the Pipfile and (more importantly) prevents it from adding the current environment to Pipfile.lock. This might be important as the current environment (i.e. the virtualenv provisioned by tox) will usually contain the current project (which may or may not be desired) and additional dependencies from tox’s deps directive. The initial provisioning may alternatively be disabled by adding skip_install = True to tox.ini.

This method requires you to be explicit about updating the lock-file, which is probably a good idea in any case.

A 3rd party plugin, tox-pipenv is also available to use Pipenv natively with tox.

☤ Shell Completion

To enable completion in fish, add this to your configuration:

eval (pipenv --completion)

Alternatively, with bash or zsh, add this to your configuration:

eval "$(pipenv --completion)"

Magic shell completions are now enabled!

✨🍰✨

☤ Working with Platform-Provided Python Components

It’s reasonably common for platform specific Python bindings for operating system interfaces to only be available through the system package manager, and hence unavailable for installation into virtual environments with pip. In these cases, the virtual environment can be created with access to the system site-packages directory:

$ pipenv --three --site-packages

To ensure that all pip-installable components actually are installed into the virtual environment and system packages are only used for interfaces that don’t participate in Python-level dependency resolution at all, use the PIP_IGNORE_INSTALLED setting:

$ PIP_IGNORE_INSTALLED=1 pipenv install --dev

☤ Pipfile vs setup.py

There is a subtle but very important distinction to be made between applications and libraries. This is a very common source of confusion in the Python community.

Libraries provide reusable functionality to other libraries and applications (let’s use the umbrella term projects here). They are required to work alongside other libraries, all with their own set of sub-dependencies. They define abstract dependencies. To avoid version conflicts in sub-dependencies of different libraries within a project, libraries should never ever pin dependency versions. Although they may specify lower or (less frequently) upper bounds, if they rely on some specific feature/fix/bug. Library dependencies are specified via install_requires in setup.py.

Libraries are ultimately meant to be used in some application. Applications are different in that they usually are not depended on by other projects. They are meant to be deployed into some specific environment and only then should the exact versions of all their dependencies and sub-dependencies be made concrete. To make this process easier is currently the main goal of Pipenv.

To summarize:

• For libraries, define abstract dependencies via install_requires in setup.py. The decision of which version exactly to be installed and where to obtain that dependency is not yours to make!
• For applications, define dependencies and where to get them in the Pipfile and use this file to update the set of concrete dependencies in Pipfile.lock. This file defines a specific idempotent environment that is known to work for your project. The Pipfile.lock is your source of truth. The Pipfile is a convenience for you to create that lock-file, in that it allows you to still remain somewhat vague about the exact version of a dependency to be used. Pipenv is there to help you define a working conflict-free set of specific dependency-versions, which would otherwise be a very tedious task.
• Of course, Pipfile and Pipenv are still useful for library developers, as they can be used to define a development or test environment.
• And, of course, there are projects for which the distinction between library and application isn’t that clear. In that case, use install_requires alongside Pipenv and Pipfile.

You can also do this:

$ pipenv install -e .

This will tell Pipenv to lock all your setup.py–declared dependencies.

☤ Changing Pipenv’s Cache Location

You can force Pipenv to use a different cache location by setting the environment variable PIPENV_CACHE_DIR to the location you wish. This is useful in the same situations that you would change PIP_CACHE_DIR to a different directory.

☤ Changing Default Python Versions

By default, Pipenv will initialize a project using whatever version of python the python3 is. Besides starting a project with the --three or --two flags, you can also use PIPENV_DEFAULT_PYTHON_VERSION to specify what version to use when starting a project when --three or --two aren’t used.

Pipenv CLI Reference

Frequently Encountered Pipenv Problems

Pipenv is constantly being improved by volunteers, but is still a very young project with limited resources, and has some quirks that needs to be dealt with. We need everyone’s help (including yours!).

Here are some common questions people have using Pipenv. Please take a look below and see if they resolve your problem.

注解

Make sure you’re running the newest Pipenv version first!

☤ Your dependencies could not be resolved

Make sure your dependencies actually do resolve. If you’re confident they are, you may need to clear your resolver cache. Run the following command:

pipenv lock --clear

and try again.

If this does not work, try manually deleting the whole cache directory. It is usually one of the following locations:

• ~/Library/Caches/pipenv (macOS)
• %LOCALAPPDATA%\pipenv\pipenv\Cache (Windows)
• ~/.cache/pipenv (other operating systems)

Pipenv does not install pre-releases (i.e. a version with an alpha/beta/etc. suffix, such as 1.0b1) by default. You will need to pass the --pre flag in your command, or set

[pipenv]
allow_prereleases = true

in your Pipfile.

☤ No module named <module name>

This is usually a result of mixing Pipenv with system packages. We strongly recommend installing Pipenv in an isolated environment. Uninstall all existing Pipenv installations, and see ☤ 安装Pipenv to choose one of the recommended way to install Pipenv instead.

☤ My pyenv-installed Python is not found

Make sure you have PYENV_ROOT set correctly. Pipenv only supports CPython distributions, with version name like 3.6.4 or similar.

☤ Pipenv does not respect pyenv’s global and local Python versions

Pipenv by default uses the Python it is installed against to create the virtualenv. You can set the --python option, or $PYENV_ROOT/shims/python to let it consult pyenv when choosing the interpreter. See ☤ 指定包的版本 for more information.

If you want Pipenv to automatically “do the right thing”, you can set the environment variable PIPENV_PYTHON to $PYENV_ROOT/shims/python. This will make Pipenv use pyenv’s active Python version to create virtual environments by default.

☤ ValueError: unknown locale: UTF-8

macOS has a bug in its locale detection that prevents us from detecting your shell encoding correctly. This can also be an issue on other systems if the locale variables do not specify an encoding.

The workaround is to set the following two environment variables to a standard localization format:

• LC_ALL
• LANG

For Bash, for example, you can add the following to your ~/.bash_profile:

export LC_ALL='en_US.UTF-8'
export LANG='en_US.UTF-8'

For Zsh, the file to edit is ~/.zshrc.

注解

You can change both the en_US and UTF-8 part to the language/locale and encoding you use.

☤ /bin/pip: No such file or directory

This may be related to your locale setting. See ☤ ValueError: unknown locale: UTF-8 for a possible solution.

☤ shell does not show the virtualenv’s name in prompt

This is intentional. You can do it yourself with either shell plugins, or clever PS1 configuration. If you really want it back, use

pipenv shell -c

instead (not available on Windows).

☤ Pipenv does not respect dependencies in setup.py

No, it does not, intentionally. Pipfile and setup.py serve different purposes, and should not consider each other by default. See ☤ Pipfile vs setup.py for more information.

☤ Using pipenv run in Supervisor program

When you configure a supervisor program’s command with pipenv run ..., you need to set locale environment variables properly to make it work.

Add this line under [supervisord] section in /etc/supervisor/supervisord.conf:

[supervisord]
environment=LC_ALL='en_US.UTF-8',LANG='en_US.UTF-8'

☤ An exception is raised during Locking dependencies…

Run pipenv lock --clear and try again. The lock sequence caches results to speed up subsequent runs. The cache may contain faulty results if a bug causes the format to corrupt, even after the bug is fixed. --clear flushes the cache, and therefore removes the bad results.

贡献指南

Development Philosophy

Pipenv is an open but opinionated tool, created by an open but opinionated developer.

Management Style

To be updated (as of March 2020).

Kenneth Reitz is the BDFL. He has final say in any decision related to the Pipenv project. Kenneth is responsible for the direction and form of the library, as well as its presentation. In addition to making decisions based on technical merit, he is responsible for making decisions based on the development philosophy of Pipenv.

Dan Ryan, Tzu-ping Chung, and Nate Prewitt are the core contributors. They are responsible for triaging bug reports, reviewing pull requests and ensuring that Kenneth is kept up to speed with developments around the library. The day-to-day managing of the project is done by the core contributors. They are responsible for making judgments about whether or not a feature request is likely to be accepted by Kenneth.

Values

• Simplicity is always better than functionality.
• Listen to everyone, then disregard it.
• The API is all that matters. Everything else is secondary.
• Fit the 90% use-case. Ignore the nay-sayers.

Contributing to Pipenv

If you’re reading this, you’re probably interested in contributing to Pipenv. Thank you very much! Open source projects live-and-die based on the support they receive from others, and the fact that you’re even considering contributing to the Pipenv project is very generous of you.

This document lays out guidelines and advice for contributing to this project. If you’re thinking of contributing, please start by reading this document and getting a feel for how contributing to this project works. If you have any questions, feel free to reach out to either Dan Ryan, Tzu-ping Chung, or Nate Prewitt, the primary maintainers.

The guide is split into sections based on the type of contribution you’re thinking of making, with a section that covers general guidelines for all contributors.

General Guidelines

Be Cordial

Be cordial or be on your way. —Kenneth Reitz

Pipenv has one very important rule governing all forms of contribution, including reporting bugs or requesting features. This golden rule is “be cordial or be on your way”.

All contributions are welcome, as long as everyone involved is treated with respect.

Get Early Feedback

If you are contributing, do not feel the need to sit on your contribution until it is perfectly polished and complete. It helps everyone involved for you to seek feedback as early as you possibly can. Submitting an early, unfinished version of your contribution for feedback in no way prejudices your chances of getting that contribution accepted, and can save you from putting a lot of work into a contribution that is not suitable for the project.

Contribution Suitability

Our project maintainers have the last word on whether or not a contribution is suitable for Pipenv. All contributions will be considered carefully, but from time to time, contributions will be rejected because they do not suit the current goals or needs of the project.

If your contribution is rejected, don’t despair! As long as you followed these guidelines, you will have a much better chance of getting your next contribution accepted.

Questions

The GitHub issue tracker is for bug reports and feature requests. Please do not use it to ask questions about how to use Pipenv. These questions should instead be directed to Stack Overflow. Make sure that your question is tagged with the pipenv tag when asking it on Stack Overflow, to ensure that it is answered promptly and accurately.

Code Contributions

Steps for Submitting Code

When contributing code, you’ll want to follow this checklist:

1. Understand our development philosophy.
2. Fork the repository on GitHub.
3. Set up your Development Setup
4. Run the tests (Testing) to confirm they all pass on your system. If they don’t, you’ll need to investigate why they fail. If you’re unable to diagnose this yourself, raise it as a bug report by following the guidelines in this document: Bug Reports.
5. Write tests that demonstrate your bug or feature. Ensure that they fail.
6. Make your change.
7. Run the entire test suite again, confirming that all tests pass including the ones you just added.
8. Send a GitHub Pull Request to the main repository’s master branch. GitHub Pull Requests are the expected method of code collaboration on this project.

The following sub-sections go into more detail on some of the points above.

Development Setup

To get your development environment setup, run:

pip install -e .
pipenv install --dev

This will install the repository version of Pipenv and then install the development dependencies. Once that has completed, you can start developing.

The repository version of Pipenv must be installed over other global versions to resolve conflicts with the pipenv folder being implicitly added to sys.path. See pypa/pipenv#2557 for more details.

Testing

Tests are written in pytest style and can be run very simply:

pytest

This will run all Pipenv tests, which can take awhile. To run a subset of the tests, the standard pytest filters are available, such as:

• provide a directory or file: pytest tests/unit or pytest tests/unit/test_cmdparse.py
• provide a keyword expression: pytest -k test_lock_editable_vcs_without_install
• provide a nodeid: pytest tests/unit/test_cmdparse.py::test_parse
• provide a test marker: pytest -m lock

Code Review

Contributions will not be merged until they have been code reviewed. You should implement any code review feedback unless you strongly object to it. In the event that you object to the code review feedback, you should make your case clearly and calmly. If, after doing so, the feedback is judged to still apply, you must either apply the feedback or withdraw your contribution.

Package Index

To speed up testing, tests that rely on a package index for locking and installing use a local server that contains vendored packages in the tests/pypi directory. Each vendored package should have it’s own folder containing the necessary releases. When adding a release for a package, it is easiest to use either the .tar.gz or universal wheels (ex: py2.py3-none). If a .tar.gz or universal wheel is not available, add wheels for all available architectures and platforms.

Documentation Contributions

Documentation improvements are always welcome! The documentation files live in the docs/ directory of the codebase. They’re written in reStructuredText, and use Sphinx to generate the full suite of documentation.

When contributing documentation, please do your best to follow the style of the documentation files. This means a soft-limit of 79 characters wide in your text files and a semi-formal, yet friendly and approachable, prose style.

When presenting Python code, use single-quoted strings ('hello' instead of "hello").

Bug Reports

Bug reports are hugely important! They are recorded as GitHub issues. Please be aware of the following things when filing bug reports:

1. Avoid raising duplicate issues. Please use the GitHub issue search feature to check whether your bug report or feature request has been mentioned in the past. Duplicate bug reports and feature requests are a huge maintenance burden on the limited resources of the project. If it is clear from your report that you would have struggled to find the original, that’s okay, but if searching for a selection of words in your issue title would have found the duplicate then the issue will likely be closed extremely abruptly.

2. When filing bug reports about exceptions or tracebacks, please include the complete traceback. Partial tracebacks, or just the exception text, are not helpful. Issues that do not contain complete tracebacks may be closed without warning.

3. Make sure you provide a suitable amount of information to work with. This means you should provide:

   • Guidance on how to reproduce the issue. Ideally, this should be a small code sample that can be run immediately by the maintainers. Failing that, let us know what you’re doing, how often it happens, what environment you’re using, etc. Be thorough: it prevents us needing to ask further questions.
   • Tell us what you expected to happen. When we run your example code, what are we expecting to happen? What does “success” look like for your code?
   • Tell us what actually happens. It’s not helpful for you to say “it doesn’t work” or “it fails”. Tell us how it fails: do you get an exception? A hang? The packages installed seem incorrect? How was the actual result different from your expected result?
   • Tell us what version of Pipenv you’re using, and how you installed it. Different versions of Pipenv behave differently and have different bugs, and some distributors of Pipenv ship patches on top of the code we supply.

   If you do not provide all of these things, it will take us much longer to fix your problem. If we ask you to clarify these and you never respond, we will close your issue without fixing it.

Run the tests

Three ways of running the tests are as follows:

1. make test (which uses docker)
2. ./run-tests.sh or run-tests.bat
3. Using pipenv:

$ git clone https://github.com/pypa/pipenv.git
$ cd pipenv
$ git submodule sync && git submodule update --init --recursive
$ pipenv install --dev
$ pipenv run pytest

For the last two, it is important that your environment is setup correctly, and this may take some work, for example, on a specific Mac installation, the following steps may be needed:

# Make sure the tests can access github
if [ "$SSH_AGENT_PID" = "" ]
then
   eval `ssh-agent`
   ssh-add
fi

# Use unix like utilities, installed with brew,
# e.g. brew install coreutils
for d in /usr/local/opt/*/libexec/gnubin /usr/local/opt/python/libexec/bin
do
  [[ ":$PATH:" != *":$d:"* ]] && PATH="$d:${PATH}"
done

export PATH

# PIP_FIND_LINKS currently breaks test_uninstall.py
unset PIP_FIND_LINKS

索引与表格。

• 索引
• 模块索引
• 搜索页面