The language defined is a compact line based format which is already in widespread use in pip requirements files, though we do not specify the command line option handling that those files permit. There is one caveat - the URL reference form, specified in PEP-440 is not actually implemented in pip, but since PEP-440 is accepted, we use that format rather than pip's current native format.

The job of a dependency is to enable tools like pip to find the right package to install. Sometimes this is very loose - just specifying a name, and sometimes very specific - referring to a specific file to install. Sometimes dependencies are only relevant in one platform, or only some versions are acceptable, so the language permits describing all these cases.

This PEP specifies the language used to describe dependencies for packages. It draws a border at the edge of describing a single dependency - the different sorts of dependencies and when they should be installed is a higher level problem. The intent is to provide a building block for higher layer specifications.

Any specification in the Python packaging ecosystem that needs to consume lists of dependencies needs to build on an approved PEP for such, but PEP-426 is mostly aspirational - and there are already existing implementations of the dependency specification which we can instead adopt. The existing implementations are battle proven and user friendly, so adopting them is arguably much better than approving an aspirational, unconsumed, format.

Examples All features of the language shown with a name based lookup: requests [security,tests] >= 2.8.1, == 2.8.* ; python_version < "2.7" A minimal URL based lookup: pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686

Concepts A dependency specification always specifies a distribution name. It may include extras, which expand the dependencies of the named distribution to enable optional features. The version installed can be controlled using version limits, or giving the URL to a specific artifact to install. Finally the dependency can be made conditional using environment markers.

Grammar We first cover the grammar briefly and then drill into the semantics of each section later. A distribution specification is written in ASCII text. We use a parsley grammar to provide a precise grammar. It is expected that the specification will be embedded into a larger system which offers framing such as comments, multiple line support via continuations, or other such features. The full grammar including annotations to build a useful parse tree is included at the end of the PEP. Versions may be specified according to the PEP-440 rules. (Note: URI is defined in std-66 ): version_cmp = wsp* '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '===' version = wsp* ( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+ version_one = version_cmp version wsp* version_many = version_one (wsp* ',' version_one)* versionspec = ( '(' version_many ')' ) | version_many urlspec = '@' wsp* <URI_reference> Environment markers allow making a specification only take effect in some environments: marker_op = version_cmp | (wsp* 'in') | (wsp* 'not' wsp+ 'in') python_str_c = (wsp | letter | digit | '(' | ')' | '.' | '{' | '}' | '-' | '_' | '*' | '#' | ':' | ';' | ',' | '/' | '?' | '[' | ']' | '!' | '~' | '`' | '@' | '$' | '%' | '^' | '&' | '=' | '+' | '|' | '<' | '>' ) dquote = '"' squote = '\\'' python_str = (squote (python_str_c | dquote)* squote | dquote (python_str_c | squote)* dquote) env_var = ('python_version' | 'python_full_version' | 'os_name' | 'sys_platform' | 'platform_release' | 'platform_system' | 'platform_version' | 'platform_machine' | 'platform_python_implementation' | 'implementation_name' | 'implementation_version' | 'extra' # ONLY when defined by a containing layer ) marker_var = wsp* (env_var | python_str) marker_expr = marker_var marker_op marker_var | wsp* '(' marker wsp* ')' marker_and = marker_expr wsp* 'and' marker_expr | marker_expr marker_or = marker_and wsp* 'or' marker_and | marker_and marker = marker_or quoted_marker = ';' wsp* marker Optional components of a distribution may be specified using the extras field: identifier_end = letterOrDigit | (('-' | '_' | '.' )* letterOrDigit) identifier = letterOrDigit identifier_end* name = identifier extras_list = identifier (wsp* ',' wsp* identifier)* extras = '[' wsp* extras_list? wsp* ']' Giving us a rule for name based requirements: name_req = name wsp* extras? wsp* versionspec? wsp* quoted_marker? And a rule for direct reference specifications: url_req = name wsp* extras? wsp* urlspec wsp+ quoted_marker? Leading to the unified rule that can specify a dependency.: specification = wsp* ( url_req | name_req ) wsp*

Whitespace Non line-breaking whitespace is mostly optional with no semantic meaning. The sole exception is detecting the end of a URL requirement.

Names Python distribution names are currently defined in PEP-345 . Names act as the primary identifier for distributions. They are present in all dependency specifications, and are sufficient to be a specification on their own. However, PyPI places strict restrictions on names - they must match a case insensitive regex or they won't be accepted. Accordingly, in this PEP we limit the acceptable values for identifiers to that regex. A full redefinition of name may take place in a future metadata PEP. The regex (run with re.IGNORECASE) is: ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$

Extras An extra is an optional part of a distribution. Distributions can specify as many extras as they wish, and each extra results in the declaration of additional dependencies of the distribution when the extra is used in a dependency specification. For instance: requests[security] Extras union in the dependencies they define with the dependencies of the distribution they are attached to. The example above would result in requests being installed, and requests own dependencies, and also any dependencies that are listed in the "security" extra of requests. If multiple extras are listed, all the dependencies are unioned together.

Versions See PEP-440 for more detail on both version numbers and version comparisons. Version specifications limit the versions of a distribution that can be used. They only apply to distributions looked up by name, rather than via a URL. Version comparison are also used in the markers feature. The optional brackets around a version are present for compatibility with PEP-345 but should not be generated, only accepted.