Pipfile
Warning: this project is under active development.
A Pipfile
, and its related Pipfile.lock
, are a new (and much better!)
replacement for pip's requirements.txt
files.
Specifically, for a Python package, 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 aPipfile
will allow seamlessly specifying groups of dependencies in one place. - This will be surfaces as only two built-in groups (default & development).
- Custom groups may be addeded in the future. Remember, it is easier to add features in the future than it is to remove them.
- Existing requirements files tend to proliferate into e.g.
- Fully specified (and deterministic) environments in the form of
Pipfile.lock
.
Example Pipfile
Note—this is an evolving work in progress:
# Note: There will be a default source, and context manager can also be used. source('https://pypi.org/', verify_ssl=True) 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')
The second parameter to package can be used positionally, but is named version.
Example Pipfile.lock
Note—this file is always to be generated, not modified or constructed by a user:
{ "_meta": { "Pipfile-sha256": "73d81f4fbe42d1da158c5d4435d921121a4a1013b2f0dfed95367f3c742b88c6", "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": "..."}, ] }
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 utilitity 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:
- Resursively 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
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.