Pipenv: Python Dev Workflow for Humans¶
Pipenv — the officially recommended Python packaging tool from Python.org, free (as in freedom).
Pipenv is a tool that aims to bring the best of all packaging worlds (bundler, composer, npm, cargo, yarn, etc.) to the Python world. Windows is a first-class citizen, in our world.
It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your Pipfile
as you install/uninstall packages. It also generates the ever-important Pipfile.lock
, which is used to produce deterministic builds.
Pipenv is primarily meant to provide users and developers of applications with an easy method to setup a working environment. For the distinction between libraries and applications and the usage of setup.py
vs Pipfile
to define dependencies, see ☤ Pipfile vs setup.py.
The problems that Pipenv seeks to solve are multi-faceted:
- You no longer need to use
pip
andvirtualenv
separately. They work together. - Managing a
requirements.txt
file can be problematic, so Pipenv usesPipfile
andPipfile.lock
to separate abstract dependency declarations from the last tested combination. - Hashes are used everywhere, always. Security. Automatically expose security vulnerabilities.
- Strongly encourage the use of the latest versions of dependencies to minimize security risks arising from outdated components.
- Give you insight into your dependency graph (e.g.
$ pipenv graph
). - Streamline development workflow by loading
.env
files.
Install Pipenv Today!¶
If you’re on MacOS, use can install Pipenv easily with Homebrew:
$ brew install pipenv
Or, if you’re using Ubuntu 17.10:
$ sudo apt install software-properties-common python-software-properties
$ sudo add-apt-repository ppa:pypa/ppa
$ sudo apt update
$ sudo apt install pipenv
Otherwise, just use pip:
$ pip install pipenv
✨🍰✨
User Testimonials¶
- Jannis Leidel, former pip maintainer—
- Pipenv is the porcelain I always wanted to build for pip. It fits my brain and mostly replaces virtualenvwrapper and manual pip calls for me. Use it.
- David Gang—
- This package manager is really awesome. For the first time I know exactly what my dependencies are which I installed and what the transitive dependencies are. Combined with the fact that installs are deterministic, makes this package manager first class, like cargo.
- Justin Myles Holmes—
- Pipenv is finally an abstraction meant to engage the mind instead of merely the filesystem.
☤ Pipenv Features¶
- Enables truly deterministic builds, while easily specifying only what you want.
- Generates and checks file hashes for locked dependencies.
- Automatically install required Pythons, if
pyenv
is available. - Automatically finds your project home, recursively, by looking for a
Pipfile
. - Automatically generates a
Pipfile
, if one doesn’t exist. - Automatically creates a virtualenv in a standard location.
- Automatically adds/removes packages to a
Pipfile
when they are un/installed. - Automatically loads
.env
files, if they exist.
The main commands are install
, uninstall
, and lock
, which generates a Pipfile.lock
. These are intended to replace $ pip install
usage, as well as manual virtualenv management (to activate a virtualenv, run $ pipenv shell
).
Basic Concepts¶
- A virtualenv will automatically be created, when one doesn’t exist.
- When no parameters are passed to
install
, all packages[packages]
specified will be installed. - To initialize a Python 3 virtual environment, run
$ pipenv --three
. - To initialize a Python 2 virtual environment, run
$ pipenv --two
. - Otherwise, whatever virtualenv defaults to will be the default.
Other Commands¶
graph
will show you a dependency graph, of your installed dependencies.shell
will spawn a shell with the virtualenv activated.run
will run a given command from the virtualenv, with any arguments forwarded (e.g.$ pipenv run python
or$ pipenv run pip freeze
).check
checks for security vulnerabilities and asserts that PEP 508 requirements are being met by the current environment.
Further Documentation Guides¶
- Basic Usage of Pipenv
- ☤ Example Pipfile & Pipfile.lock
- ☤ General Recommendations & Version Control
- ☤ Example Pipenv Workflow
- ☤ Example Pipenv Upgrade Workflow
- ☤ Importing from requirements.txt
- ☤ Specifying Versions of a Package
- ☤ Specifying Versions of Python
- ☤ Editable Dependencies (e.g.
-e .
) - ☤ Environment Management with Pipenv
- ☤ About Shell Configuration
- ☤ A Note about VCS Dependencies
- ☤ Pipfile.lock Security Features
- Advanced Usage of Pipenv
- ☤ Caveats
- ☤ Specifying Package Indexes
- ☤ Injecting credentials into Pipfiles via environment variables
- ☤ Specifying Basically Anything
- ☤ Deploying System Dependencies
- ☤
pipenv
andconda
- ☤ Generating a
requirements.txt
- ☤ Detection of Security Vulnerabilities
- ☤ Community Integrations
- ☤ Open a Module in Your Editor
- ☤ Automatic Python Installation
- ☤ Automatic Loading of
.env
- ☤ Support for Environment Variables
- ☤ Configuration With Environment Variables
- ☤ Custom Virtual Environment Location
- ☤ Testing Projects
- ☤ Shell Completion
- ☤ Working with Platform-Provided Python Components
- ☤ Pipfile vs setup.py
- Frequently Encountered Pipenv Problems
- ☤ Your dependencies could not be resolved
- ☤ No module named <module name>
- ☤ My pyenv-installed Python is not found
- ☤ Pipenv does not respect pyenv’s global and local Python versions
- ☤ ValueError: unknown locale: UTF-8
- ☤ /bin/pip: No such file or directory
- ☤
shell
does not show the virtualenv’s name in prompt - ☤ Pipenv does not respect dependencies in setup.py
☤ Pipenv Usage¶
pipenv¶
pipenv [OPTIONS] COMMAND [ARGS]...
Options
-
--where
¶
Output project home information.
-
--venv
¶
Output virtualenv information.
-
--py
¶
Output Python interpreter information.
-
--envs
¶
Output Environment Variable options.
-
--rm
¶
Remove the virtualenv.
-
--bare
¶
Minimal output.
-
--completion
¶
Output completion (to be eval’d).
-
--man
¶
Display manpage.
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
--site-packages
¶
Enable site-packages for the virtualenv.
-
--version
¶
Show the version and exit.
check¶
pipenv check [OPTIONS] [ARGS]...
Options
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
--system
¶
Use system Python.
-
--unused
<unused>
¶ Given a code path, show potentially unused dependencies.
Arguments
-
ARGS
¶
Optional argument(s)
clean¶
pipenv clean [OPTIONS]
Options
-
-v
,
--verbose
¶
Verbose mode.
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
--dry-run
¶
Just output unneeded packages.
graph¶
pipenv graph [OPTIONS]
Options
-
--bare
¶
Minimal output.
-
--json
¶
Output JSON.
-
--reverse
¶
Reversed dependency graph.
install¶
pipenv install [OPTIONS] [PACKAGE_NAME] [MORE_PACKAGES]...
Options
-
-d
,
--dev
¶
Install package(s) in [dev-packages].
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
--system
¶
System pip management.
-
-r
,
--requirements
<requirements>
¶ Import a requirements.txt file.
-
-c
,
--code
<code>
¶ Import from codebase.
-
-v
,
--verbose
¶
Verbose mode.
-
--ignore-pipfile
¶
Ignore Pipfile when installing, using the Pipfile.lock.
-
--sequential
¶
Install dependencies one-at-a-time, instead of concurrently.
-
--skip-lock
¶
Ignore locking mechanisms when installing—use the Pipfile, instead.
-
--deploy
¶
Abort if the Pipfile.lock is out–of–date, or Python version is wrong.
-
--pre
¶
Allow pre–releases.
-
--keep-outdated
¶
Keep out–dated dependencies from being updated in Pipfile.lock.
-
--selective-upgrade
¶
Update specified packages.
Arguments
-
PACKAGE_NAME
¶
Optional argument
-
MORE_PACKAGES
¶
Optional argument(s)
lock¶
pipenv lock [OPTIONS]
Options
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
-v
,
--verbose
¶
Verbose mode.
-
-r
,
--requirements
¶
Generate output compatible with requirements.txt.
-
-d
,
--dev
¶
Generate output compatible with requirements.txt for the development dependencies.
-
--clear
¶
Clear the dependency cache.
-
--pre
¶
Allow pre–releases.
-
--keep-outdated
¶
Keep out–dated dependencies from being updated in Pipfile.lock.
open¶
pipenv open [OPTIONS] MODULE
Options
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
Arguments
-
MODULE
¶
Required argument
run¶
pipenv run [OPTIONS] COMMAND [ARGS]...
Options
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
Arguments
-
COMMAND
¶
Required argument
-
ARGS
¶
Optional argument(s)
shell¶
pipenv shell [OPTIONS] [SHELL_ARGS]...
Options
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
--fancy
¶
Run in shell in fancy mode (for elegantly configured shells).
-
--anyway
¶
Always spawn a subshell, even if one is already spawned.
Arguments
-
SHELL_ARGS
¶
Optional argument(s)
sync¶
pipenv sync [OPTIONS]
Options
-
-v
,
--verbose
¶
Verbose mode.
-
-d
,
--dev
¶
Additionally install package(s) in [dev-packages].
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
--bare
¶
Minimal output.
-
--clear
¶
Clear the dependency cache.
-
--sequential
¶
Install dependencies one-at-a-time, instead of concurrently.
uninstall¶
pipenv uninstall [OPTIONS] [PACKAGE_NAME] [MORE_PACKAGES]...
Options
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
--system
¶
System pip management.
-
-v
,
--verbose
¶
Verbose mode.
-
--lock
¶
Lock afterwards.
-
--all-dev
¶
Un-install all package from [dev-packages].
-
--all
¶
Purge all package(s) from virtualenv. Does not edit Pipfile.
-
--keep-outdated
¶
Keep out–dated dependencies from being updated in Pipfile.lock.
Arguments
-
PACKAGE_NAME
¶
Optional argument
-
MORE_PACKAGES
¶
Optional argument(s)
update¶
pipenv update [OPTIONS] [MORE_PACKAGES]... [PACKAGE]
Options
-
--three
,
--two
¶
Use Python 3/2 when creating virtualenv.
-
--python
<python>
¶ Specify which version of Python virtualenv should use.
-
-v
,
--verbose
¶
Verbose mode.
-
-d
,
--dev
¶
Install package(s) in [dev-packages].
-
--clear
¶
Clear the dependency cache.
-
--bare
¶
Minimal output.
-
--pre
¶
Allow pre–releases.
-
--keep-outdated
¶
Keep out–dated dependencies from being updated in Pipfile.lock.
-
--sequential
¶
Install dependencies one-at-a-time, instead of concurrently.
-
--outdated
¶
List out–of–date dependencies.
-
--dry-run
¶
List out–of–date dependencies.
Arguments
-
MORE_PACKAGES
¶
Optional argument(s)
-
PACKAGE
¶
Optional argument