CEP 29: `MatchSpec` minilanguage by jaimergp · Pull Request #82 · conda/ceps

jaimergp · 2024-06-04T14:11:17Z

Checklist for submitter

I am submitting a new CEP: MatchSpec minilanguage.
- I am using the CEP template by creating a copy cep-0000.md named cep-XXXX.md in the root level.
I am submitting modifications to CEP XX.
Something else: (add your description here).

Checklist for CEP approvals

The vote period has ended and the vote has passed the necessary quorum and approval thresholds.
A new CEP number has been minted. Usually, this is ${greatest-number-in-main} + 1.
The cep-XXXX.md file has been renamed accordingly.
The # CEP XXXX - header has been edited accordingly.
The CEP status in the table has been changed to approved.
The last modification date in the table has been updated accordingly.
The pre-commit checks are passing.

Closes #80

jaimergp · 2024-06-04T14:11:57Z

I'm seeing myself referring to the "MatchSpec" interface in other CEPs yet this is not standardized, so there we go. Let's open that can of worms.

jaimergp · 2024-06-05T09:55:32Z

This will probably need another CEP on PackageRecord, which will probably ask for Repodata counterparts and... channel structure. Yay. I like how packaging.python.org does this btw. I'll probably copy some of that structure.

cep-9999.md

cep-??.md

JeanChristopheMorinPerso · 2024-06-06T20:54:10Z

cep-??.md

+
+### Exact matches
+
+To fully-specify a package record with a full, exact spec, these fields must be given as exact values: `channel` (preferrably by URL), `subdir`, `name`, `version`, `build`. Alternatively, an exact spec can also be given by `*[md5=12345678901234567890123456789012]` or `*[sha256=f453db4ffe2271ec492a2913af4e61d4a6c118201f07de757df0eff769b65d2e]`.


When matching by checksum, should you also add the subdir? If I'm not mistaken, it's possible for two subdirs to contain a package with the same checksum right? Or is this a corner case?

These checksums are coming from the compressed artifacts, so in principle they should be unique (even with unique contents, the index.json file should have "subdir": <subdir>, I think?).

The hash that conda-build uses for the build_string doesn't consider the subdir, indeed (and maybe it should).

Just FYI, rattler does not currently support this. There we require that at least the package name is still specified.

baszalmstra

Thanks for the great write up @jaimergp !

baszalmstra · 2024-06-13T14:14:19Z

cep-??.md

+
+The simplest form merely consists of up to three positional arguments: `name [version [build]]`. Only `name` is required. `version` can be any version specifier. `build` can be any string matcher. See "Match conventions" below.
+
+The positional syntax also allows the `=` character as a separator, instead of a space. When this is the case, versions are interpreted differently. `pkg=1.8` will be taken as `1.8.*` (fuzzy), but `pkg 1.8` will give `1.8` (exact). To have fuzzy matches with the space syntax, you need to use `pkg =1.8`. This nuance does not apply if a `build` string is present; both `foo==1.0=*` and `foo=1.0=*` are equivalent (they both understand the version as `1.0`, exact).


I know this is just reporting the current state of affairs but, jucky.

In rattler, this form is no longer allowed when parsing in strict mode. (still accepted in lenient parsing mode).

@baszalmstra which form is not allowed?
~~IIRC in mamba pkg 1.8 and pkg =1.8 are the same.~~

The form foo=1.0=bla is disallowed! (in strict mode only, used in rattler build)

cep-??.md

cep-9999.md

cep-??.md

baszalmstra · 2024-06-13T14:34:35Z

cep-??.md

+
+### Exact matches
+
+To fully-specify a package record with a full, exact spec, these fields must be given as exact values: `channel` (preferrably by URL), `subdir`, `name`, `version`, `build`. Alternatively, an exact spec can also be given by `*[md5=12345678901234567890123456789012]` or `*[sha256=f453db4ffe2271ec492a2913af4e61d4a6c118201f07de757df0eff769b65d2e]`.


Just FYI, rattler does not currently support this. There we require that at least the package name is still specified.

cep-0029.md

ruben-arts · 2024-07-25T14:12:47Z

cep-9999.md

+6. If `channel` is an exact value and `subdir` is an exact value, `subdir` is appended to
+   `channel` with a `/` separator. Otherwise, `subdir` is included in the key-value brackets.


How does this related to the label channels? e.g. pytorch/label/nightly::libfaiss?
With the seperator logic this will be assumed to be a subdir.

The logic in conda is to take the last component and compare it against known subdirs. As a result, channels cannot be named like subdirs. e. g. I can't register a channel named linux-64.

Hind-M · 2024-12-16T11:19:54Z

Not sure about the current status of this CEP, but before moving forward with it, we should maybe consider finalizing this one if we think it could be of interest?

jaimergp · 2025-01-09T20:51:29Z

cep-9999.md

+
+These are also accepted but have reduced utility. Their usage is discouraged:
+
+- `url`


Note that a full URL can be parsed into a MatchSpec object so... should a URL be considered a valid form? In those cases, a note: parsers need to account for %-decoding. See xref conda/conda#14481.

cep-9999.md

Co-authored-by: Bas Zalmstra <zalmstra.bas@gmail.com>

Co-authored-by: JeanChristopheMorinPerso <JeanChristopheMorinPerso@users.noreply.github.com>

jaimergp · 2025-09-26T16:48:52Z

@baszalmstra, @beckermr, @AntoinePrv, @ruben-arts, @JeanChristopheMorinPerso, I've tackled some of the pending items if you want to take a look. Perhaps more critically, the version strings and ordering conversation is now part of #132.

I think I'll rewrite part of the Specification so we don't lose time with historical details and go straight for the syntax, since it's all intertwined anyway... This is valid 🤦:

>>> str(MS("channel:namespace:pkg 1 2[subdir=linux-63,channel=XX,name=jaime]"))
'XX/linux-63::pkg==1=2'

jaimergp · 2026-02-16T11:52:44Z

msarahan

Thanks for writing this up. As mentioned in comments, I think you bend backwards too much to support legacy stuff. It makes the descriptions more complicated. Just declare what the standard should be, and then separately describe the legacy stuff that is still supported, but should be avoided where possible.

cep-XXXX.md

msarahan · 2026-02-23T14:35:22Z

cep-0029.md

+- Ordered comparison, with the implied ordering described in [CEP PR #132](https://github.com/conda/ceps/pull/132):
+  - Exclusive ordered comparison, expressed as a version literal prefixed by `<` or `>`, MUST be interpreted as "smaller than" and "greater than", respectively, as per their position in the version ordering scheme.
+  - Inclusive ordered comparison, expressed as a version literal prefixed by one of these strings: `<=`, `>=`, MUST be interpreted as "exclusive ordered comparison", respectively, but they will also match if their position is equivalent in the version ordering scheme.
+- Semver-like comparisons, expressed as a version literal prefixed by the `~=` string, MUST be interpreted as greater than or equal to the version literal while also matching a fuzzy equality test for the version literal sans its last segment (e.g. `~=0.5.3` expands to `>=0.5.3,0.5.*`). This operator is considered deprecated, and its expanded alternative SHOULD be used instead.


Suggested change

- Semver-like comparisons, expressed as a version literal prefixed by the `~=` string, MUST be interpreted as greater than or equal to the version literal while also matching a fuzzy equality test for the version literal sans its last segment (e.g. `~=0.5.3` expands to `>=0.5.3,0.5.*`). This operator is considered deprecated, and its expanded alternative SHOULD be used instead.

- Semver-like "[compatible release](https://peps.python.org/pep-0440/#compatible-release)" comparisons, expressed as a version literal prefixed by the `~=` string, MUST be interpreted as greater than or equal to the version literal while also matching a fuzzy equality test for the version literal sans its last segment (e.g. `~=0.5.3` expands to `>=0.5.3,0.5.*`). This operator is considered deprecated, and its expanded alternative SHOULD be used instead.

This could also expand to >=0.5.3,<0.6, but then we get into pre-release goofiness with the 0a0 stuff. I guess the glob also has that problem, though. Or maybe this has been fixed and I'm just old.

msarahan · 2026-02-23T14:38:44Z

cep-0029.md

+
+### Version expression parsing
+
+In the name of backwards compatibility, the (`name`, `version`, `build`) group in the `MatchSpec` syntax allows two types of separators: spaces and a single `=` character. This conditions how certain `version` expressions are parsed. Given a _version literal_ denoted as `version-literal` (i.e. no operators or asterisks), the following rules MUST apply:


I think you should describe the current standard, and then mention legacy syntax that MUST be supported (or not)

msarahan · 2026-02-23T14:43:33Z

cep-0029.md

+pkg=1.8.*=*
+pkg =1.8.* *
+pkg ==1.8.* *
+pkg[version=1.8.*]


I think it would help clarify the syntax descriptions above if you had one of these examples for each syntax element. Expressing things in words is kind of unnatural for these symbolic expressions, which are by definition ways of expressing things more clearly and concisely than words.

Even better might be example matches, like:

<2 would match: 0.9 1.0 1.99 1.99.5a0 2.0a0 but not: 2.0

Perhaps this can be an expandable block to not visually bloat the document.

msarahan · 2026-02-23T14:47:10Z

cep-0029.md

+
+The new syntax had to maintain backwards compatibility with the space- and `=`-separated forms too. This is the reason behind some surprising behaviors discussed in the specification above.
+
+Advanced expressions like lookaround and backreferences are discouraged because they can incur performance issues leading to DOS and other security problems.


So it's ok to use if I'm behind my corporate firewall? Where specifically should they be discouraged? In specs that are shared with others to create environments? Conda env files? I don't understand where the performance issue occurs. If it is within my local host, then that's just conda being slow. Perhaps that is a concern on shared infrastructure. On the other hand, if it affects the repos, then that is a very different story.

msarahan · 2026-02-23T14:48:40Z

cep-0029.md

+- `@feature`: a way to require the, now deprecated, features (e.g. `@mkl`)
+- `channel[subdir]::name`: a non ambiguous way to add subdir information to the positional channel field (instead of slash separation). Keyword argument is preferred for disambiguation. By dropping this syntax, we only assign one meaning to square brackets: key-value pairs.
+
+Future work may introduce a stricter syntax subset that further reduces the ambiguity in the specification (e.g. disallowing space-separated name-version-build triplets).


Define the strict subset here! Just mention that there are also some legacy things that are still supported, and may be deprecated and removed in the future.

jaimergp · 2026-02-27T20:25:05Z

Thanks @msarahan, I'll apply the editorial changes shortly, but some of that feedback will change the CEP too much at this time. I'll make a note for a future revision of the MatchSpec specification, though.

jaimergp · 2026-02-27T20:25:09Z

@CJ-Wright @chenghlee @marcelotrevisani @mbargull @jakirkham, gentle reminder to cast your vote on this CEP.

jaimergp · 2026-03-03T12:30:13Z

The voting period has concluded. This is a CEP vote, so it requires 60% of the steering council to vote to reach quorum, and a 60% of affirmative votes to pass. However, since it was open for more than two weeks and three reminders were sent (actually, four), it also qualifies for timeout rules, where the quorum threshold is simply five people.

Size of the steering council: 15
- Number of votes: 13 -> 86.67%
  - Yes: 13 -> 100%
  - No: 0
  - Abstain: 0
- Did not vote: 2

This CEP has passed 🎉.

Co-authored-by: msarahan <msarahan@users.noreply.github.com>

Add CEP for MatchSpec minilanguage

f392cb6

jaimergp mentioned this pull request Jun 4, 2024

CEP request: Document MatchSpec #80

Closed

2 tasks

JeanChristopheMorinPerso reviewed Jun 6, 2024

View reviewed changes

jaimergp mentioned this pull request Jun 7, 2024

Discrepancy creating a MatchSpec from package strings (sometimes "==" gets stripped) conda/conda#13932

Closed

2 tasks

baszalmstra reviewed Jun 13, 2024

View reviewed changes

ruben-arts reviewed Jul 25, 2024

View reviewed changes

jjerphan mentioned this pull request Sep 30, 2024

maint: Improve the parser of MatchSpec mamba-org/mamba#3463

Open

jjerphan mentioned this pull request Dec 4, 2024

MatchSpec parsing error with ~= version operator mamba-org/mamba#3647

Closed

3 tasks

jaimergp commented Jan 9, 2025

View reviewed changes

h-vetinari mentioned this pull request Jan 26, 2025

Hint against =-separated match specs conda-forge/conda-smithy#2232

Merged

2 tasks

jaimergp mentioned this pull request Apr 14, 2025

[CEP 26] Identifying Packages and Channels in the conda Ecosystem #116

Merged

beckermr reviewed Apr 14, 2025

View reviewed changes

cep-9999.md Outdated Show resolved Hide resolved

jaimergp and others added 10 commits September 26, 2025 16:28

Merge branch 'main' of github.com:conda/ceps into matchspec

e2dfdbb

add namespace

5a3c4e0

add example glob -> regex

fbb8ddb

Address review suggestions

6836bc7

Co-authored-by: Bas Zalmstra <zalmstra.bas@gmail.com>

Small detail

80455ab

clarify different syntaxes

7a8e3a2

Satisfy linter

8e79b58

Rename for linter

9afdba3

Disallow mixing *

4d56cce

clarify discouraged keywords

76112fb

jaimergp mentioned this pull request Sep 26, 2025

Remove * from valid version characters #60

Open

jaimergp and others added 2 commits September 26, 2025 18:42

link to sections

318cf31

Co-authored-by: JeanChristopheMorinPerso <JeanChristopheMorinPerso@users.noreply.github.com>

pre-commit

20e98d5

jaimergp changed the title ~~Add CEP for MatchSpec minilanguage~~ CEP XXXX: MatchSpec minilanguage Sep 26, 2025

jaimergp added 13 commits January 31, 2026 11:46

Clarify subdirs in :: syntax

51fe606

Allow spaces around commas

ae60f20

String matching is always case insensitive

c5c3bb1

Discourage advanced regex matching

a935207

Clary globs can be multiple

1d2ec1f

Allow parenthese for version clause grouping

54d249c

Elaborate types of clauses

3c33e73

Correct different variations of globbing and literal version matching

9800aec

Use blocks instead of paragraphs

0774130

Move Fully specified expressions to appendix

5dc6ea5

Move canonical representation to appendix

b1a1ac0

pre-commit

69083bf

Write down exotic syntax that was dropped from the standard.

8879ed4

jaimergp force-pushed the matchspec branch from 2c230cc to 8879ed4 Compare January 31, 2026 10:59

jaimergp added 3 commits February 15, 2026 18:03

add 'test' to backticks

79e4e2c

Minor editorial changes

c0fecf4

Add RFC2119 note

b81ae1f

jaimergp added 2 commits February 20, 2026 13:07

Minor editorial changes

555fa5b

Missing tr

65c5daa

msarahan approved these changes Feb 23, 2026

View reviewed changes

jaimergp and others added 3 commits March 4, 2026 10:47

Merge branch 'main' of github.com:conda/ceps into matchspec

649ae4c

Mint as 29. Update references and status

c825e25

Clearer wording in some parts of the specification

ac7a3e9

Co-authored-by: msarahan <msarahan@users.noreply.github.com>

jaimergp changed the title ~~CEP XXXX: MatchSpec minilanguage~~ CEP 29: MatchSpec minilanguage Mar 4, 2026

jaimergp merged commit eb6cd51 into conda:main Mar 4, 2026
1 check passed

jaimergp deleted the matchspec branch March 4, 2026 10:32


		### Exact matches

		To fully-specify a package record with a full, exact spec, these fields must be given as exact values: `channel` (preferrably by URL), `subdir`, `name`, `version`, `build`. Alternatively, an exact spec can also be given by `[md5=12345678901234567890123456789012]` or `[sha256=f453db4ffe2271ec492a2913af4e61d4a6c118201f07de757df0eff769b65d2e]`.


		The simplest form merely consists of up to three positional arguments: `name [version [build]]`. Only `name` is required. `version` can be any version specifier. `build` can be any string matcher. See "Match conventions" below.

		The positional syntax also allows the `=` character as a separator, instead of a space. When this is the case, versions are interpreted differently. `pkg=1.8` will be taken as `1.8.` (fuzzy), but `pkg 1.8` will give `1.8` (exact). To have fuzzy matches with the space syntax, you need to use `pkg =1.8`. This nuance does not apply if a `build` string is present; both `foo==1.0=` and `foo=1.0=*` are equivalent (they both understand the version as `1.0`, exact).

		6. If `channel` is an exact value and `subdir` is an exact value, `subdir` is appended to
		`channel` with a `/` separator. Otherwise, `subdir` is included in the key-value brackets.


		These are also accepted but have reduced utility. Their usage is discouraged:

		- `url`


		### Version expression parsing

		In the name of backwards compatibility, the (`name`, `version`, `build`) group in the `MatchSpec` syntax allows two types of separators: spaces and a single `=` character. This conditions how certain `version` expressions are parsed. Given a _version literal_ denoted as `version-literal` (i.e. no operators or asterisks), the following rules MUST apply:


		The new syntax had to maintain backwards compatibility with the space- and `=`-separated forms too. This is the reason behind some surprising behaviors discussed in the specification above.

		Advanced expressions like lookaround and backreferences are discouraged because they can incur performance issues leading to DOS and other security problems.

Conversation

jaimergp commented Jun 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist for submitter

Checklist for CEP approvals

Uh oh!

jaimergp commented Jun 4, 2024

Uh oh!

jaimergp commented Jun 5, 2024

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

baszalmstra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AntoinePrv Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

baszalmstra Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hind-M commented Dec 16, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jaimergp commented Sep 26, 2025

Uh oh!

jaimergp commented Feb 16, 2026 • edited by mbargull Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

msarahan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaimergp commented Feb 27, 2026

Uh oh!

jaimergp commented Feb 27, 2026

Uh oh!

jaimergp commented Mar 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

jaimergp commented Jun 4, 2024 •

edited

Loading

AntoinePrv Apr 15, 2025 •

edited

Loading

baszalmstra Apr 15, 2025 •

edited

Loading

jaimergp commented Feb 16, 2026 •

edited by mbargull

Loading