pipenv簡單使用

摘要

本文是pipenv文章系列的第二篇。標題稱“簡單使用”也許不切題，可能會有人覺得內容並不是很簡單。總之，算是入門的文字，請自動略過感覺過深的部分。以下正文開始。

pipenv可整合pip, virtualenv與pyenv的使用，大幅簡化建立Python虛擬環境的工作方式。它會是廣泛採用的方式。

Pipenv功用

• 可高度整合pip, virtualenv, pyenv的功能，將虛擬環境的建置與包(package)安裝、升級等維護之繁雜工作簡化。
• 若有pyenv，可藉著它來自動安裝所需要的Python版號（限CPython版，且不支援3.8-dev之類版號）。
• 可自動記錄、維護並區分開發/產品環境所需要的不同包。不再需要維護requirements.txt這類記錄。
• 可檢查虛擬環境與包的軟體安全漏洞。
• 可顯示包的依賴關係。
• 若有.env檔，可從中自動帶入環境變數。
• pyenv install語法與pip install的完全相容。

安裝/更新

安裝

$ pip3 install --user pipenv

裝好可能會出現這樣的警示訊息：

WARNING: The script virtualenv is installed in '/home/fygul/.local/bin' which is not on PATH.
Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
WARNING: The script virtualenv-clone is installed in '/home/fygul/.local/bin' which is not on PATH.
Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
WARNING: The scripts pipenv and pipenv-resolver are installed in '/home/fygul/.local/bin' which is not on PATH.
Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.

可在 .bashrc 尾端加入：

export PATH="$HOME/.local/bin:$PATH"

若想啟用 Shell Completion，在 .bashrc 中加入：

$(pipenv --completion)

安裝好後另開shell讓新設定生效。

註：萬一遇到pip3執行上的問題，修改usr/bin/pip3，將其中的

from pip import main

改成

from pip._internal import main

更新

$ pip3 install --user --upgrade pipenv

注意

• Pipenv自動把專案對映到指定的虛擬環境。
• 虛擬環境採用專案目錄名稱加上專案目錄完整路徑的hash值做名稱。
• 如果變更了專案的路徑會破壞了此預設對映，而無法找到原來的虛擬環境。
• 若想避免往後路徑變更的問題，可在.bashrc加上 export PIPENV_VENV_IN_PROJECT=1，讓虛擬環境建立在專案目錄中。

顯示虛擬環境路徑：

$ pipenv --venv

Pipenv的使用

簡單例子

建立新專案

建立並進入放專案用的目錄，以pipenv建立虛擬環境：

$ mkdir testproj
$ cd testproj
$ pipenv --python 3.7.4 install requests

安裝好後，這目錄中只會出現兩個純文字檔案Pipfile, Pipfile.lock，實際的虛擬環境檔案所在會有訊息提示，也會提示如何啟用虛擬環境，或者不進入虛擬環境而直接執行其中指令的方式。
 

註：在這安裝階段，若遇到出現Locking等半天，要耐心等一下，因安裝的東西較多，會花點時間下載，這點可從網路流量看出來。下圖是另一個虛擬環境安裝過程的擷圖，這個就花了此時間等待：

啟用Pipevn shell進入虛擬環境：

$ pipenv shell
(venv) $ python --version

要離開時可輸入exit或按Ctrl+D。

或者，也可以像以下方式不進入虛擬環境而直接執行其中的命令：

$ pipenv run [COMMAND]
$ pipenv run pip freeze

可以開始慣用的編輯器來進行專案開發工作。PyCharm可支援pipenv，以它開啟此專案目錄，它會知道虛擬環境直譯器的位置。其他有支援pipenv的可見Community Integrations。

軟體交付

假定這專案完成後決定以源碼交付，將此目錄複製到客戶的機器上。在客戶的機器上先裝好必要的Python, pip, pyenv與pipenv，進入該目錄，一行指令即可建置好虛擬環境並安裝好所要的包：

$ pipenv install

此時該指令會從該目錄中找到兩個pipenv產生的檔案，從中讀取內容並自動建構好軟體運行的工作環境。

Pipfile與Pipfile.lock

pipenv產生的兩個檔案：

1. Pipfile：記錄包的下載源、開發期/產品期所需安裝的包、Python版號。其內容格式採用TOML。
2. Pipfile.lock：依Pipfile所產生的資訊，像已安裝包的版號與一些hash值。

此二檔案都是純文字檔，在必要時，可以修改調整Pipfile的內容。

pipenv常用選項與命令

單獨輸入pipenv時會顯示常用選項與命令，還有使用範例。指令的基本型式：

pipenv [OPTIONS] COMMAND [ARGS]...

以下是較常用的，未列出詳細的命令選項。

指定安裝的版號

幾個例子：

$ pipenv install "requests~=2.2"  # 相當於 ==2.*
$ pipenv install "requests>2.19"
$ pipenv --python 3.7.4

環境管理

三個主要管理pipenv環境的命令是install, uninstall與lock。

• pipenv install [package names]：用來安裝包。此命令的許多選項，以下有些命令也會有。
  • --two | --three | --python：指定安裝到虛擬環境的Python版號。
  • --dev：同時安裝Pipfile中develop與default的包。
  • --skip-lock：忽略Pipfile.lock的內容，也不更新它。
  • -r, --requirements ：匯入requirements.txt。
  • -e, --editable ：可編輯的包URL或路徑，後述。
  • --pypi-mirror ：指定PyPI鏡像源，後述。
• pipenv unistall [package names]：用來移除包。支援install的所有參數，還有以下二個：
  • --all：從虛擬環境中清除所有檔案，但不動Pipfile。
  • --all-dev：從虛擬環境中移除所有開發包，並從Pipfile中移除它們。
• pipenv lock：建立Pipfile.lock，其中記錄專案所有的依賴包、最新可得版本、目前下載檔案的hash。
• pipenv sync：安裝Pipfile.lock中所有的包。
• pipenv update [package names]：更新包，即lock後再sync。
  • --outdated：列出過時的相依。
• pipenv clear：移除沒列在Pipfile.lock中的包。
• pipenv --venv：顯示虛擬環境資訊。
• pipenv --rm：移除虛擬環境。
• pipenv --clear：清除pip, pipenv的cache。

使用requirements.txt

如果非得要使用requirements.txt的話，也是可以。

若初建立專案執行pipenv install時只有一個requirements.txt，pipenv會自動從中匯入其內容並建立Pipfile。

也可指定要匯入的需求檔，如：

$ pipenv install -r path/to/requirements.txt

update與lock命令也有 -r 選項。

如果想產生requirements.txt：

$ pipenv lock -r

或者，可利用pip指令原有的功能，如：

$ pipenv run pip freeze > requirements.txt

其他

顯示包的依賴

$ pipenv graph

檢查安全弱點

$ pipenv check

可編輯的包路徑

install, uninstall, update三個命令都有 -e 選項，用來告訴pipenv，某個包路徑是可編輯改動的，如：

$ pipenv install -dev -e .

此例是指到本目錄。之後也可以手工調整Pipfile中的path，以改變包的安裝來源。

使用VCS

可從git之類的Version Control Systems來安裝包，URL格式：<vcs_type>+<scheme>://<location>/<user_or_organization>/<repository>@<branch_or_tag>#egg=<package_name>

其中的@是選項段。強烈建議以可編輯模式來安裝這類包。

例子像：

$ pipenv install -e git+https://github.com/agermanidis/autosub.git#egg=autosub

詳細可參見pip的VCS Support。

其他注意

• 有時在安裝包時可能會遇上花很長時間做 lock的情況，避免之道是insall時加上 --skip-lock 選項，待整個安裝工作完成之後再pipenv lock。
• 在Pipfile中提供的wheel包不會被 $pipenv lock 納入。

進階使用

指定Package Indexes

若想調整package index的url，可打開Pipfile，修改[[source]]區段中的url值。或者再增加一個區段，以加入另一個。

也可以指定package使用哪個package index，如以下[packages]區段中2個不同包使用了不同的index：

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

較清楚的說明可見Specifying Package Indexes。

使用PyPI鏡像

install, update, sync, lock, uninstall命令都有個 --pypi-mirror 參數，以方便改用指定鏡像的URL來安裝包，而不是用預設的PyPI。或者，另一種做法，也可設定 PIPENV_PYPI_MIRROR 環境變數。

如果你到大陸，也許會想改用當地的鏡像，這是其中一個：pypi 镜像使用帮助，給pip用的，但其中的URL可給pipenv用。

若對建立PyPI鏡像有興趣，可見：

• PyPI 镜像源使用帮助
• PyPI Repositories

以編輯器開啟module

以 EDITOR 環境變數的編輯器開啟目前專案中的module：

$ pipenv open [module name]

自動載入環境變數

如果專案中有個 .env 檔案，裡面寫好需要的環境變數，pipenv shell與pipenv run會自動從中載入。

結語

在某種程度上，pipenv可取代了pip與virtualenv的用法。如果對後二者的用法生疏了，也沒什麼關係，只要清楚它們的作用，直接使用pipenv就可以，而且整個使用流程也簡化許多。
本文只做了簡單介紹，並非詳細，細節可見後面參考中所列的官方文件。

參考

1. Python Development Workflow for Humans
2. Pipenv: Python Dev Workflow for Humans
3. Pipenv & Virtual Environments
4. Basic Usage of Pipenv
5. Advanced Usage of Pipenv
6. Frequently Encountered Pipenv Problems

update: 2020-9-18