Pipenv: Python Development Workflow for Humans ============================================== .. image:: https://img.shields.io/pypi/v/pipenv.svg :target: https://pypi.python.org/pypi/pipenv .. image:: https://img.shields.io/pypi/l/pipenv.svg :target: https://pypi.python.org/pypi/pipenv .. image:: https://img.shields.io/pypi/pyversions/pipenv.svg :target: https://pypi.python.org/pypi/pipenv .. image:: https://travis-ci.org/kennethreitz/pipenv.svg?branch=master :target: https://travis-ci.org/kennethreitz/pipenv .. image:: https://img.shields.io/appveyor/ci/kennethreitz/pipenv.svg :target: https://ci.appveyor.com/project/kennethreitz/pipenv/branch/master .. image:: https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg :target: https://saythanks.io/to/kennethreitz --------------- **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. .. image:: http://media.kennethreitz.com.s3.amazonaws.com/pipenv.gif The problems that Pipenv seeks to solve are multi-faceted: - You no longer need to use ``pip`` and ``virtualenv`` separately. They work together. - Managing a ``requirements.txt`` file `can be problematic `_, so Pipenv uses the upcoming ``Pipfile`` and ``Pipfile.lock`` instead, which is superior for basic use cases. - Hashes are used everywhere, always. Security. Automatically expose security vulnerabilities. - Give you insight into your dependency graph (e.g. ``$ pipenv graph``). - Streamline development workflow by loading ``.env`` files. Installation ------------ :: $ pip install pipenv Or if you are on macOS, you can install Pipenv via `Homebrew `_ with: :: $ brew 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.* **Justin Myles Holmes**— *Pipenv is finally an abstraction meant to engage the mind instead of merely the filesystem.* **Isaac Sanders**— *Pipenv is literally the best thing about my day today. Thanks, Kenneth!* ☤ 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 ////////////// - ``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``). - ``check`` asserts that PEP 508 requirements are being met by the current environment. - ``graph`` will print a pretty graph of all your installed dependencies. Shell Completion //////////////// For example, with fish, put this in your ``~/.config/fish/completions/pipenv.fish``:: eval (pipenv --completion) Alternatively, with bash, put this in your ``.bashrc`` or ``.bash_profile``:: eval "$(pipenv --completion)" Magic shell completions are now enabled! There is also a `fish plugin `_, which will automatically activate your subshells for you! Fish is the best shell. You should use it. ☤ Usage ------- :: $ pipenv Usage: pipenv [OPTIONS] COMMAND [ARGS]... Options: --update Update Pipenv & pip to latest. --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 TEXT Specify which version of Python virtualenv should use. --site-packages Enable site-packages for the virtualenv. --jumbotron An easter egg, effectively. --version Show the version and exit. -h, --help Show this message and exit. Usage Examples: Create a new project using Python 3.6, specifically: $ pipenv --python 3.6 Install all dependencies for a project (including dev): $ pipenv install --dev Create a lockfile containing pre-releases: $ pipenv lock --pre Show a graph of your installed dependencies: $ pipenv graph Check your installed dependencies for security vulnerabilties: $ pipenv check Install a local setup.py into your virtual environment/Pipfile: $ pipenv install -e . Commands: check Checks for security vulnerabilities and... graph Displays currently–installed dependency graph... install Installs provided packages and adds them to... lock Generates Pipfile.lock. open View a given module in your editor. run Spawns a command installed into the... shell Spawns a shell within the virtualenv. uninstall Un-installs a provided package and removes it... update Uninstalls all packages, and re-installs... Locate the project:: $ pipenv --where /Users/kennethreitz/Library/Mobile Documents/com~apple~CloudDocs/repos/kr/pipenv/test Locate the virtualenv:: $ pipenv --venv /Users/kennethreitz/.local/share/virtualenvs/test-Skyy4vre Locate the Python interpreter:: $ pipenv --py /Users/kennethreitz/.local/share/virtualenvs/test-Skyy4vre/bin/python Install packages:: $ pipenv install Creating a virtualenv for this project... ... No package provided, installing all dependencies. Virtualenv location: /Users/kennethreitz/.local/share/virtualenvs/test-EJkjoYts Installing dependencies from Pipfile.lock... ... To activate this project's virtualenv, run the following: $ pipenv shell Install a dev dependency:: $ pipenv install pytest --dev Installing pytest... ... Adding pytest to Pipfile's [dev-packages]... Show a dependency graph:: $ pipenv graph requests==2.18.4 - certifi [required: >=2017.4.17, installed: 2017.7.27.1] - chardet [required: >=3.0.2,<3.1.0, installed: 3.0.4] - idna [required: >=2.5,<2.7, installed: 2.6] - urllib3 [required: <1.23,>=1.21.1, installed: 1.22] Generate a lockfile:: $ pipenv lock Assuring all dependencies from Pipfile are installed... Locking [dev-packages] dependencies... Locking [packages] dependencies... Note: your project now has only default [packages] installed. To install [dev-packages], run: $ pipenv install --dev Install all dev dependencies:: $ pipenv install --dev Pipfile found at /Users/kennethreitz/repos/kr/pip2/test/Pipfile. Considering this to be the project home. Pipfile.lock out of date, updating... Assuring all dependencies from Pipfile are installed... Locking [dev-packages] dependencies... Locking [packages] dependencies... Uninstall everything:: $ pipenv uninstall --all No package provided, un-installing all dependencies. Found 25 installed package(s), purging... ... Environment now purged and fresh! Use the shell:: $ pipenv shell Loading .env environment variables… Launching subshell in virtual environment. Type 'exit' or 'Ctrl+D' to return. $ ▯ ☤ Documentation --------------- Documentation resides over at `pipenv.org `_.