mirror of
https://github.com/kennethreitz/pipenv.git
synced 2026-06-05 22:50:18 +00:00
Matt Davis
761a03d088
* Begin reviewing the basics docs. * Check in delta * More doc revisions. * Split apart basics docs. * Refactor based on building docs * add the files back as markdown. * more conversions to markdown. * more conversions to markdown. * fix markdown formatting. * convert index to markdown. * More docs review * More markdown and doc revisions. * Fix docs. * Update doc build requirements. * fix lint * Fix build with update/upgrade command. * remove useless quickstart and update the commands section. * Fix lint * change ordering of table of contents. * fix changelog duplicate headings. * Start splitting advanced topics. * minor nits * Move some sections from advanced to shell. * remove this section as its stale and kind of off topic. * move scripts out into its own section. * Wrap up revisions1 * fix lint * address PR feedback and other nits. * fix lint * Try improving ordering of table of contents, fix issue with indexes.md file location. * fix lint * PR feedback.
266 lines
14 KiB
Markdown
266 lines
14 KiB
Markdown
# Pipfile & Pipfile.lock
|
|
|
|
`Pipfile` contains the specification for the project top-level requirements and any desired specifiers.
|
|
This file is managed by the developers invoking pipenv commands.
|
|
The `Pipfile` uses inline tables and the [TOML Spec](https://github.com/toml-lang/toml#user-content-spec>).
|
|
|
|
`Pipfile.lock` replaces the `requirements.txt` file used in most Python projects and adds
|
|
security benefits of tracking the packages hashes that were last locked.
|
|
This file is managed automatically through locking actions.
|
|
|
|
You should add both `Pipfile` and `Pipfile.lock` to the project's source control.
|
|
|
|
## Example Pipfile
|
|
|
|
Here is a simple example of a `Pipfile` and the resulting `Pipfile.lock`.
|
|
|
|
[[source]]
|
|
url = "https://pypi.org/simple"
|
|
verify_ssl = true
|
|
name = "pypi"
|
|
|
|
[packages]
|
|
Django = "==4.*"
|
|
waitress = {version = "*", markers="sys_platform == 'win32'"}
|
|
gunicorn = {version = "*", markers="sys_platform == 'linux'"}
|
|
|
|
[dev-packages]
|
|
pytest-cov = "==3.*"
|
|
|
|
|
|
## Example Pipfile.lock
|
|
|
|
{
|
|
"_meta": {
|
|
"hash": {
|
|
"sha256": "d09f41c21ecfb3b019ace66b61ea1174f99e8b0da0d39e70a5c1cf2363d8b88d"
|
|
},
|
|
"pipfile-spec": 6,
|
|
"requires": {},
|
|
"sources": [
|
|
{
|
|
"name": "pypi",
|
|
"url": "https://pypi.org/simple",
|
|
"verify_ssl": true
|
|
}
|
|
]
|
|
},
|
|
"default": {
|
|
"asgiref": {
|
|
"hashes": [
|
|
"sha256:71e68008da809b957b7ee4b43dbccff33d1b23519fb8344e33f049897077afac",
|
|
"sha256:9567dfe7bd8d3c8c892227827c41cce860b368104c3431da67a0c5a65a949506"
|
|
],
|
|
"markers": "python_version >= '3.7'",
|
|
"version": "==3.6.0"
|
|
},
|
|
"django": {
|
|
"hashes": [
|
|
"sha256:44f714b81c5f190d9d2ddad01a532fe502fa01c4cb8faf1d081f4264ed15dcd8",
|
|
"sha256:f2f431e75adc40039ace496ad3b9f17227022e8b11566f4b363da44c7e44761e"
|
|
],
|
|
"index": "pypi",
|
|
"version": "==4.1.7"
|
|
},
|
|
"gunicorn": {
|
|
"hashes": [
|
|
"sha256:9dcc4547dbb1cb284accfb15ab5667a0e5d1881cc443e0677b4882a4067a807e",
|
|
"sha256:e0a968b5ba15f8a328fdfd7ab1fcb5af4470c28aaf7e55df02a99bc13138e6e8"
|
|
],
|
|
"index": "pypi",
|
|
"markers": "sys_platform == 'linux'",
|
|
"version": "==20.1.0"
|
|
},
|
|
"setuptools": {
|
|
"hashes": [
|
|
"sha256:95f00380ef2ffa41d9bba85d95b27689d923c93dfbafed4aecd7cf988a25e012",
|
|
"sha256:bb6d8e508de562768f2027902929f8523932fcd1fb784e6d573d2cafac995a48"
|
|
],
|
|
"markers": "python_version >= '3.7'",
|
|
"version": "==67.3.2"
|
|
},
|
|
"sqlparse": {
|
|
"hashes": [
|
|
"sha256:0323c0ec29cd52bceabc1b4d9d579e311f3e4961b98d174201d5622a23b85e34",
|
|
"sha256:69ca804846bb114d2ec380e4360a8a340db83f0ccf3afceeb1404df028f57268"
|
|
],
|
|
"markers": "python_version >= '3.5'",
|
|
"version": "==0.4.3"
|
|
},
|
|
"waitress": {
|
|
"hashes": [
|
|
"sha256:7500c9625927c8ec60f54377d590f67b30c8e70ef4b8894214ac6e4cad233d2a",
|
|
"sha256:780a4082c5fbc0fde6a2fcfe5e26e6efc1e8f425730863c04085769781f51eba"
|
|
],
|
|
"markers": "sys_platform == 'win32'",
|
|
"version": "==2.1.2"
|
|
}
|
|
},
|
|
"develop": {
|
|
"attrs": {
|
|
"hashes": [
|
|
"sha256:29e95c7f6778868dbd49170f98f8818f78f3dc5e0e37c0b1f474e3561b240836",
|
|
"sha256:c9227bfc2f01993c03f68db37d1d15c9690188323c067c641f1a35ca58185f99"
|
|
],
|
|
"markers": "python_version >= '3.6'",
|
|
"version": "==22.2.0"
|
|
},
|
|
"coverage": {
|
|
"extras": [
|
|
"toml"
|
|
],
|
|
"hashes": [
|
|
"sha256:04481245ef966fbd24ae9b9e537ce899ae584d521dfbe78f89cad003c38ca2ab",
|
|
"sha256:0c45948f613d5d18c9ec5eaa203ce06a653334cf1bd47c783a12d0dd4fd9c851",
|
|
"sha256:10188fe543560ec4874f974b5305cd1a8bdcfa885ee00ea3a03733464c4ca265",
|
|
"sha256:218fe982371ac7387304153ecd51205f14e9d731b34fb0568181abaf7b443ba0",
|
|
"sha256:29571503c37f2ef2138a306d23e7270687c0efb9cab4bd8038d609b5c2393a3a",
|
|
"sha256:2a60d6513781e87047c3e630b33b4d1e89f39836dac6e069ffee28c4786715f5",
|
|
"sha256:2bf1d5f2084c3932b56b962a683074a3692bce7cabd3aa023c987a2a8e7612f6",
|
|
"sha256:3164d31078fa9efe406e198aecd2a02d32a62fecbdef74f76dad6a46c7e48311",
|
|
"sha256:32df215215f3af2c1617a55dbdfb403b772d463d54d219985ac7cd3bf124cada",
|
|
"sha256:33d1ae9d4079e05ac4cc1ef9e20c648f5afabf1a92adfaf2ccf509c50b85717f",
|
|
"sha256:33ff26d0f6cc3ca8de13d14fde1ff8efe1456b53e3f0273e63cc8b3c84a063d8",
|
|
"sha256:38da2db80cc505a611938d8624801158e409928b136c8916cd2e203970dde4dc",
|
|
"sha256:3b155caf3760408d1cb903b21e6a97ad4e2bdad43cbc265e3ce0afb8e0057e73",
|
|
"sha256:3b946bbcd5a8231383450b195cfb58cb01cbe7f8949f5758566b881df4b33baf",
|
|
"sha256:3baf5f126f30781b5e93dbefcc8271cb2491647f8283f20ac54d12161dff080e",
|
|
"sha256:4b14d5e09c656de5038a3f9bfe5228f53439282abcab87317c9f7f1acb280352",
|
|
"sha256:51b236e764840a6df0661b67e50697aaa0e7d4124ca95e5058fa3d7cbc240b7c",
|
|
"sha256:63ffd21aa133ff48c4dff7adcc46b7ec8b565491bfc371212122dd999812ea1c",
|
|
"sha256:6a43c7823cd7427b4ed763aa7fb63901ca8288591323b58c9cd6ec31ad910f3c",
|
|
"sha256:755e89e32376c850f826c425ece2c35a4fc266c081490eb0a841e7c1cb0d3bda",
|
|
"sha256:7a726d742816cb3a8973c8c9a97539c734b3a309345236cd533c4883dda05b8d",
|
|
"sha256:7c7c0d0827e853315c9bbd43c1162c006dd808dbbe297db7ae66cd17b07830f0",
|
|
"sha256:7ed681b0f8e8bcbbffa58ba26fcf5dbc8f79e7997595bf071ed5430d8c08d6f3",
|
|
"sha256:7ee5c9bb51695f80878faaa5598040dd6c9e172ddcf490382e8aedb8ec3fec8d",
|
|
"sha256:8361be1c2c073919500b6601220a6f2f98ea0b6d2fec5014c1d9cfa23dd07038",
|
|
"sha256:8ae125d1134bf236acba8b83e74c603d1b30e207266121e76484562bc816344c",
|
|
"sha256:9817733f0d3ea91bea80de0f79ef971ae94f81ca52f9b66500c6a2fea8e4b4f8",
|
|
"sha256:98b85dd86514d889a2e3dd22ab3c18c9d0019e696478391d86708b805f4ea0fa",
|
|
"sha256:9ccb092c9ede70b2517a57382a601619d20981f56f440eae7e4d7eaafd1d1d09",
|
|
"sha256:9d58885215094ab4a86a6aef044e42994a2bd76a446dc59b352622655ba6621b",
|
|
"sha256:b643cb30821e7570c0aaf54feaf0bfb630b79059f85741843e9dc23f33aaca2c",
|
|
"sha256:bc7c85a150501286f8b56bd8ed3aa4093f4b88fb68c0843d21ff9656f0009d6a",
|
|
"sha256:beeb129cacea34490ffd4d6153af70509aa3cda20fdda2ea1a2be870dfec8d52",
|
|
"sha256:c31b75ae466c053a98bf26843563b3b3517b8f37da4d47b1c582fdc703112bc3",
|
|
"sha256:c4e4881fa9e9667afcc742f0c244d9364d197490fbc91d12ac3b5de0bf2df146",
|
|
"sha256:c5b15ed7644ae4bee0ecf74fee95808dcc34ba6ace87e8dfbf5cb0dc20eab45a",
|
|
"sha256:d12d076582507ea460ea2a89a8c85cb558f83406c8a41dd641d7be9a32e1274f",
|
|
"sha256:d248cd4a92065a4d4543b8331660121b31c4148dd00a691bfb7a5cdc7483cfa4",
|
|
"sha256:d47dd659a4ee952e90dc56c97d78132573dc5c7b09d61b416a9deef4ebe01a0c",
|
|
"sha256:d4a5a5879a939cb84959d86869132b00176197ca561c664fc21478c1eee60d75",
|
|
"sha256:da9b41d4539eefd408c46725fb76ecba3a50a3367cafb7dea5f250d0653c1040",
|
|
"sha256:db61a79c07331e88b9a9974815c075fbd812bc9dbc4dc44b366b5368a2936063",
|
|
"sha256:ddb726cb861c3117a553f940372a495fe1078249ff5f8a5478c0576c7be12050",
|
|
"sha256:ded59300d6330be27bc6cf0b74b89ada58069ced87c48eaf9344e5e84b0072f7",
|
|
"sha256:e2617759031dae1bf183c16cef8fcfb3de7617f394c813fa5e8e46e9b82d4222",
|
|
"sha256:e5cdbb5cafcedea04924568d990e20ce7f1945a1dd54b560f879ee2d57226912",
|
|
"sha256:ec8e767f13be637d056f7e07e61d089e555f719b387a7070154ad80a0ff31801",
|
|
"sha256:ef382417db92ba23dfb5864a3fc9be27ea4894e86620d342a116b243ade5d35d",
|
|
"sha256:f2cba5c6db29ce991029b5e4ac51eb36774458f0a3b8d3137241b32d1bb91f06",
|
|
"sha256:f5b4198d85a3755d27e64c52f8c95d6333119e49fd001ae5798dac872c95e0f8",
|
|
"sha256:ffeeb38ee4a80a30a6877c5c4c359e5498eec095878f1581453202bfacc8fbc2"
|
|
],
|
|
"markers": "python_version >= '3.7'",
|
|
"version": "==7.1.0"
|
|
},
|
|
"iniconfig": {
|
|
"hashes": [
|
|
"sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3",
|
|
"sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374"
|
|
],
|
|
"markers": "python_version >= '3.7'",
|
|
"version": "==2.0.0"
|
|
},
|
|
"packaging": {
|
|
"hashes": [
|
|
"sha256:714ac14496c3e68c99c29b00845f7a2b85f3bb6f1078fd9f72fd20f0570002b2",
|
|
"sha256:b6ad297f8907de0fa2fe1ccbd26fdaf387f5f47c7275fedf8cce89f99446cf97"
|
|
],
|
|
"markers": "python_version >= '3.7'",
|
|
"version": "==23.0"
|
|
},
|
|
"pluggy": {
|
|
"hashes": [
|
|
"sha256:4224373bacce55f955a878bf9cfa763c1e360858e330072059e10bad68531159",
|
|
"sha256:74134bbf457f031a36d68416e1509f34bd5ccc019f0bcc952c7b909d06b37bd3"
|
|
],
|
|
"markers": "python_version >= '3.6'",
|
|
"version": "==1.0.0"
|
|
},
|
|
"pytest": {
|
|
"hashes": [
|
|
"sha256:c7c6ca206e93355074ae32f7403e8ea12163b1163c976fee7d4d84027c162be5",
|
|
"sha256:d45e0952f3727241918b8fd0f376f5ff6b301cc0777c6f9a556935c92d8a7d42"
|
|
],
|
|
"markers": "python_version >= '3.7'",
|
|
"version": "==7.2.1"
|
|
},
|
|
"pytest-cov": {
|
|
"hashes": [
|
|
"sha256:578d5d15ac4a25e5f961c938b85a05b09fdaae9deef3bb6de9a6e766622ca7a6",
|
|
"sha256:e7f0f5b1617d2210a2cabc266dfe2f4c75a8d32fb89eafb7ad9d06f6d076d470"
|
|
],
|
|
"index": "pypi",
|
|
"version": "==3.0.0"
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
## Importing from requirements.txt
|
|
|
|
For projects utilizing a `requirements.txt` pipenv can import the contents of this file and create a
|
|
`Pipfile` and `Pipfile.lock` for you:
|
|
|
|
$ pipenv install -r path/to/requirements.txt
|
|
|
|
If your requirements file has version numbers pinned, you'll likely want to edit the new `Pipfile`
|
|
to only keep track of top level dependencies and let `pipenv` keep track of pinning sub-dependencies in the lock file.
|
|
|
|
|
|
## Pipfile.lock Security Features
|
|
|
|
`Pipfile.lock` leverages the security of package hash validation in `pip`.
|
|
The `Pipfile.lock` is generated with the sha256 hashes of each downloaded package.
|
|
This guarantees you're installing the same exact packages on any network as the one
|
|
where the lock file was last updated, even on untrusted networks.
|
|
|
|
We recommend designing CI/CD deployments whereby the build does not alter the lock file as a side effect.
|
|
In other words, you can use `pipenv lock` or `pipenv upgrade` to adjust your lockfile through local development,
|
|
the PR process and approve those lock changes before deploying to production that version of the lockfile.
|
|
In other words avoid having your CI issue `lock`, `update`, `upgrade` `uninstall` or `install` commands that will relock.
|
|
Note: It is counterintuitive that `pipenv install` re-locks and `pipenv sync` or `pipenv install --deploy` does not.
|
|
Based on feedback, we may change this behavior of `pipenv install` to not re-lock in the future but be mindful of this when designing CI pipelines today.
|
|
|
|
```{admonition} Generate requirements.txt output from lock file
|
|
$ pipenv requirements
|
|
```
|
|
|
|
## Package Category Groups
|
|
|
|
Pipenv supports arbitrarily named package categories in the Pipfile/Pipfile.lock for organizing dependencies into different groups.
|
|
|
|
Traditionally there were only two package groups, and they were named different between the `Pipfile` and `Pipfile.lock`:
|
|
|
|
* `packages` in the `Pipfile` corresponds to `default` group in the lockfile.
|
|
* `dev-packages` in the `Pipfile` corresponds to `develop` group in the lockfile.
|
|
|
|
The default/packages group is what you interact with when specifying no particular categories,
|
|
whereas the develop/dev-packages group is typically what you interact with when specifying the `--dev` or `-d` flag.
|
|
|
|
Beginning in `pipenv==2022.10.9` support for named package categories was generalized such that any
|
|
non-reserved keywords may be used to create named package groups other than the original groups.
|
|
All named categories (other than the special default/develop) will use the category name consistently between the `Pipfile` and `Pipfile.lock`
|
|
|
|
## General Notes and Recommendations
|
|
|
|
- Keep both `Pipfile` and `Pipfile.lock` in version control.
|
|
- `pipenv install` adds specifiers to `Pipfile` and rebuilds the lock file based on the Pipfile specs, by utilizing the internal resolver of `pip`.
|
|
- Not all the required sub-dependencies need be specified in `Pipfile`, instead only add specifiers that make sense for the stability of your project.
|
|
Example: `requests` requires `cryptography` but (for reasons) you want to ensure `cryptography` is pinned to a particular version set.
|
|
- Consider specifying your target Python version in your `Pipfile`'s `[requires]` section.
|
|
For this use either `python_version` in the format `X.Y` (or `X`) or `python_full_version` in `X.Y.Z` format.
|
|
- Considering making use of named package categories to further isolate dependency install groups for large monoliths.
|