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.

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.

[pipenv] Directives

Pipfile may contain a [pipenv] section to control the behaviour of pipenv itself. Some available settings include:

• allow_prereleases - Tell pipenv to install pre-release versions of a package -i.e. a version with an alpha/beta/etc. suffix, such as 1.0b1. Equivalent to passing the --pre flag on the command line.

• disable_pip_input - Prevent pipenv from asking for input. Equivalent to the --no-input flag.

• install_search_all_sources - Allow installation of packages from an existing Pipfile.lock to search all defined indexes for the constrained package version and hash signatures. See Specifying Package Indexes.

• sort_pipfile - Sort package names alphabetically inside each category. Categories will be sorted and updated on install and uninstall. This is purely cosmetic to make reading easier for humans, and has no effect on installation order or dependency resolution. Note that Pipfile.lock packages are always sorted alphabetically.

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.

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.