Pipfile

Warning: this project is under active development (and design).

A Pipfile, and its related Pipfile.lock, are a new (and much better!) replacement for pip's requirements.txt files.

Specifically, for a Python application, a Pipfile allows developers to specify concrete and sets of dependencies, their locations, and their loose version constraints. A Pipfile.lock can then be automatically generated during package installation to fully specify an exact set of known working versions, and future installations may refer to the Pipfile.lock to recreate the exact contents of the environment in a deterministic manner. A deployed web application, for instance, can be completely redeployed with the same exact versions of all recursive dependencies, by referencing the Pipfile.lock file.

pip will grow a new command line option, -p / --pipfile to install the versions specified in a Pipfile, similar to its existing -r / --requirement argument for installing requirements.txt files.

This repository contains the design specification of the Pipfile format, as well as (soon) an implementation of a parser for the specification which can be used by pip and any other consumer, once the API (including the form of a Pipfile itself) has been built out and finalized.

The Concept

A Pipfile will be superior to a requirements.txt file in a number of ways:

• Python-like syntax for declaring all types of Python dependencies.
• One Pipfile (as opposed to multiple requirements.txt files).
  • Existing requirements files tend to proliferate into e.g. dev-requirements.txt, test-requirements.txt, etc., but a Pipfile will allow seamlessly specifying groups of dependencies in one place.
  • This will be surfaced as only two built-in groups (default & development).
  • Custom groups may be added in the future. Remember, it is easier to add features in the future than it is to remove them. The Composer community has been successful with only default and development as group options for many years — I'd like to follow this model, at first.
• Fully specified (and deterministic) environments in the form of Pipfile.lock.

Example Pipfile

Note—this is an evolving work in progress:

source('https://pypi.org/', verify_ssl=True)

requires_python('2.7')

package('requests', extras=['socks'])
package('Django', '>1.10')
package('pinax', git='git://github.com/pinax/pinax.git', ref='1.4', editable=True)
dev_package('nose')

Notes:

• There will be a default source(), and a context manager can also be used.
• The second parameter to package is used positionally, but also named version.
• An underlying PEP 508 requires(marker, specifier) will be allowed, but discouraged in favor for a small selection of built-ins for standard use-cases (e.g. python version, platform). This functionality may not be readily used, as it is only to assert (and therefore abort, if appropriate) installation on certain platforms (e.g. windows, wrong python version).

Other / lower-level functions:

# Support for all PEP 508 markers
requires('python_full_version', '3.6.0b1')

#TODO: shortcut name for Darwin|Linux (e.g. `*nix`)
requires_platform('Windows')

Example Pipfile.lock

Note—this file is always to be generated, not modified or constructed by a user:

{
    "_meta": {
        "Pipfile-sha256": "73d81f4fbe42d1da158c5d4435d921121a4a1013b2f0dfed95367f3c742b88c6",
        "requires": [
            {"marker": "python_version", "specifier": "2.7"}
        ],
        "sources": [
            {"url": "https://pypi.org/", "verify_ssl": true},
        ]
     },
    "default": [
        {"name": "Django", "version": "1.10.3", "hash": "..."},
        {"name": "requests", "version": "2.12.1", "hash": "..."},
        {"name": "pinax", "git": "git://...", "ref": "1.4", "editable": true},
        {"name": "PySocks", "version": "1.5.6", "hash": "..."},
    ],
    "development": [
        {"name": "nose", "version": "1.3.7", "hash": "..."},
    ]
}

Note how the versions of each dependency are recursively frozen, and a hash gets computed so that you can take advantage of new pip security features

Why not TOML & Friends?

TOML is an attractive option for Pipfile, especially with the recent PEP 518 (pyproject.tml) plans that are in place.

Don't worry — this and other formats are possibly being considered for the contents Pipfile.

The focus at the moment is on getting the Python representation perfect before proceeding with true prototypes with existing markup languages. However, we are optimizing for ease of typing for the end-user (no googling / boilerplate / copypasta required!), so the Python-esque syntax (AST-powered) will, at this time, likely exist in the final version. But, this is being constantly re-evaluated.

It's all about making an API for Humans, first. Machines, second. Ideally, both of these can co-exist in harmony. For example, if this Python-esque syntax is settled on, a parser (this library, actually) will be readily available and may have a command-line utility for converting the representation to JSON.

Example Pip Integration (eventually)

Install packages from Pipfile:

$ pip install -p
! Warning: Pipfile.lock (48d35f) is out of date. Updating to (73d81f).
Installing packages from Pipfile.lock...

# Manually update lockfile.
$ pip freeze -p Pipfile
Pipfile.lock (73d81f) written to disk.

Notes:

# -p accepts a path argument, which defaults to 'Pipfile'.
# Pipfile.lock will be written automatically during `install -p` if it does not exist.

Ideas:

- Recursively look for `Pipfile` in parent directories (limit 4?) when ``-p`` is bare.

Useful Links

• pypa/pip#1795: Requirements 2.0
• Basic Concept Gist (fork of @dstufft's)

Inspirations

• nvie/pip-tools: A set of tools to keep your pinned Python dependencies fresh.
• A Better Pip Workflow by Kenneth Reitz
• Taking lessons-learned from Composer, Cargo, Yarn, NPM, Bundler, and friends.

Documentation

The documentation for this project will (eventually) reside at pypi.org.

Discussion

If you run into bugs, you can file them in our issue tracker.

You can also join #pypa on Freenode to ask questions or get involved.

Code of Conduct

Everyone interacting in the pipfile project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct.