Improve Clarity of packageManager Checksum Notation

tl;dr: Corepack version string should use = character for clarity instead of +
"packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674..."

The packageManager field in package.json currently uses a + symbol to separate the package manager version from its checksum (e.g., "pnpm@10.7.0+sha512..."). This + notation can be misleading for developers, as it is commonly associated with version ranges or build metadata in other contexts (e.g., 1.0.0+build123). This leads to potential misinterpretation, where users might incorrectly assume it signifies "version 10.7.0 or higher" rather than an exact version with an associated integrity hash.

The checksum is intended to enforce an exact, immutable match for the package manager's binary, ensuring reproducibility and security. The current + symbol, however, can obscure this exactness.

Proposed Solution

We propose changing the separator between the package manager version and its checksum from + to =.

Current:

"packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"

Proposed:

"packageManager": "pnpm@10.7.0=sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"

Justification:

Using = would more clearly convey that the hash represents an exact match for the preceding version, eliminating ambiguity and aligning better with the deterministic nature of the checksum. This change would:

Improve Clarity: Make it immediately obvious that the entire string after @ is a precise identifier, not a flexible range.
Reduce Misinterpretation: Prevent developers from mistakenly assuming version compatibility beyond the exact specified version.
Enhance User Experience: Reduce cognitive load and potential confusion, especially for new users or those less familiar with Corepack's specific notation.

Current Behavior

Corepack correctly uses the hash for integrity verification. The issue is purely with the visual representation and the potential for misinterpretation due to the + symbol's common usage in other versioning schemes.

Thank you for considering this improvement.

@rotu

What do you think @rotu @aduh95

Appending the checksum onto a version specifier was a poor choice from the outset. The checksum belongs in some sort of lockfile, NOT in package.json.
The reason for using + is because the semver package and similar tooling does tolerate the + without affecting version precedence. If you try to use semver to parse a malformed version string (like one with a =), it will throw an error.

That is, I think this is not worth doing.

Appending the checksum onto a version specifier was a poor choice from the outset. The checksum belongs in some sort of lockfile, NOT in package.json.

The reason for using + is because the semver package and similar tooling does tolerate the + without affecting version precedence. If you try to use semver to parse a malformed version string (like one with a =), it will throw an error.

That is, I think this is not worth doing.

I don't care about the specifics. Just fix the confusion.

I'm fine with the syntax as it is.

I don't care about the specifics. Just fix the confusion.

The only confusing thing to me is that it visually appears to be a package name specifier even though it has different semantics.

It's well-documented here:

corepack/README.md

Lines 89 to 114 in 0b492c9

    
           ### When Authoring Packages 
        
           Set your package's manager with the `packageManager` field in `package.json`: 
        
           ```json 
        
           { 
        
             "packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa" 
        
           } 
        
           ``` 
        
           Here, `yarn` is the name of the package manager, specified at version `3.2.3`, 
        
           along with the SHA-224 hash of this version for validation. 
        
           `packageManager@x.y.z` is required. The hash is optional but strongly 
        
           recommended as a security practice. Permitted values for the package manager are 
        
           `yarn`, `npm`, and `pnpm`. 
        
           You can also provide a URL to a `.js` file (which will be interpreted as a 
        
           CommonJS module) or a `.tgz` file (which will be interpreted as a package, and 
        
           the `"bin"` field of the `package.json` will be used to determine which file to 
        
           use in the archive). 
        
           ```json 
        
           { 
        
             "packageManager": "yarn@https://registry.npmjs.org/@yarnpkg/cli-dist/-/cli-dist-3.2.3.tgz#sha224.16a0797d1710d1fb7ec40ab5c3801b68370a612a9b66ba117ad9924b" 
        
           } 
        
           ```

perhaps that documentation is not discoverable enough?

Navigation Menu

Repository navigation

Improve Clarity of `packageManager` Checksum Notation #726

Proposed Solution

Current Behavior

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	### When Authoring Packages

	Set your package's manager with the `packageManager` field in `package.json`:

	```json
	{
	"packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa"
	}
	```

	Here, `yarn` is the name of the package manager, specified at version `3.2.3`,
	along with the SHA-224 hash of this version for validation.
	`packageManager@x.y.z` is required. The hash is optional but strongly
	recommended as a security practice. Permitted values for the package manager are
	`yarn`, `npm`, and `pnpm`.

	You can also provide a URL to a `.js` file (which will be interpreted as a
	CommonJS module) or a `.tgz` file (which will be interpreted as a package, and
	the `"bin"` field of the `package.json` will be used to determine which file to
	use in the archive).

	```json
	{
	"packageManager": "yarn@https://registry.npmjs.org/@yarnpkg/cli-dist/-/cli-dist-3.2.3.tgz#sha224.16a0797d1710d1fb7ec40ab5c3801b68370a612a9b66ba117ad9924b"
	}
	```

Improve Clarity of packageManager Checksum Notation #726

Description

Proposed Solution

Current Behavior

Activity

AMDphreak commented on Jul 13, 2025

rotu commented on Jul 14, 2025

AMDphreak commented on Jul 22, 2025

arcanis commented on Jul 22, 2025

rotu commented on Jul 22, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Improve Clarity of `packageManager` Checksum Notation #726