Add a design doc for deterministic pack by omajid · Pull Request #14785 · NuGet/Home

omajid · 2026-03-03T20:00:32Z

No description provided.

omajid · 2026-03-03T20:02:06Z

cc @nkolev92 @zivkan

accepted/2026/deterministic-pack-revisited.md

accepted/2026/deterministic-pack.md

accepted/2026/deterministic-pack-revisited.md

accepted/2026/deterministic-pack.md

accepted/2026/deterministic-pack-revisited.md

omajid · 2026-03-04T19:00:36Z

I added a note about the PackageBuilder API change too.

accepted/2026/deterministic-pack-revisited.md

akoeplinger · 2026-03-05T17:13:51Z

accepted/2026/deterministic-pack-revisited.md

+  available through the binlog.
+
+- Package signing breaks the possibility of bit-by-bit reproducibility, due to
+  embedding a timestamp. Nuget has the concept of a contnet hash, that can


Suggested change

embedding a timestamp. Nuget has the concept of a contnet hash, that can

embedding a timestamp. NuGet has the concept of a content hash, that can

you could still strip the signature before comparing the packages right? if yes, that doesn't sound like a big deal to me

Good point. I am worried about the sha hashes in the .deps.json files, though.

.deps.json shouldn't be in the nuget packages though? or do you mean when you build an app with the sdk?

ah they could be for tools packages. I wonder how that works today?

They also end up in the .NET SDK itself:

$ find /usr/lib64/dotnet -iname '*.deps.json' /usr/lib64/dotnet/packs/Microsoft.AspNetCore.App.Runtime.fedora.43-x64/10.0.3/runtimes/fedora.43-x64/lib/net10.0/Microsoft.AspNetCore.App.deps.json /usr/lib64/dotnet/packs/Microsoft.NETCore.App.Runtime.fedora.43-x64/10.0.3/runtimes/fedora.43-x64/lib/net10.0/Microsoft.NETCore.App.deps.json /usr/lib64/dotnet/shared/Microsoft.NETCore.App/10.0.3/Microsoft.NETCore.App.deps.json /usr/lib64/dotnet/shared/Microsoft.AspNetCore.App/10.0.3/Microsoft.AspNetCore.App.deps.json /usr/lib64/dotnet/sdk/10.0.103/Containers/tasks/net10.0/Microsoft.NET.Build.Containers.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-dev-certs/10.0.3-servicing.26075.103/tools/net10.0/any/dotnet-dev-certs.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-format/BuildHost-netcore/Microsoft.CodeAnalysis.Workspaces.MSBuild.BuildHost.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-format/dotnet-format.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-user-jwts/10.0.3-servicing.26075.103/tools/net10.0/any/dotnet-user-jwts.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-user-secrets/10.0.3-servicing.26075.103/tools/net10.0/any/dotnet-user-secrets.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-watch/10.0.103/tools/net10.0/any/BuildHost-netcore/Microsoft.CodeAnalysis.Workspaces.MSBuild.BuildHost.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-watch/10.0.103/tools/net10.0/any/dotnet-watch.deps.json /usr/lib64/dotnet/sdk/10.0.103/DotnetTools/dotnet-watch/10.0.103/tools/net10.0/any/dotnet.deps.json /usr/lib64/dotnet/sdk/10.0.103/FSharp/fsc.deps.json /usr/lib64/dotnet/sdk/10.0.103/FSharp/fsi.deps.json /usr/lib64/dotnet/sdk/10.0.103/Roslyn/bincore/VBCSCompiler.deps.json /usr/lib64/dotnet/sdk/10.0.103/Roslyn/bincore/csc.deps.json /usr/lib64/dotnet/sdk/10.0.103/Roslyn/bincore/vbc.deps.json /usr/lib64/dotnet/sdk/10.0.103/Roslyn/Microsoft.Build.Tasks.CodeAnalysis.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.Build.Tasks.Git/tools/net/Microsoft.Build.Tasks.Git.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.NET.Sdk.BlazorWebAssembly/tools/net10.0/Microsoft.NET.Sdk.BlazorWebAssembly.Tool.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.NET.Sdk.Razor/source-generators/Microsoft.CodeAnalysis.Razor.Compiler.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.NET.Sdk.Razor/tools/rzc.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.NET.Sdk.StaticWebAssets/tools/net10.0/Microsoft.NET.Sdk.StaticWebAssets.Tool.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.SourceLink.AzureRepos.Git/tools/net/Microsoft.SourceLink.AzureRepos.Git.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.SourceLink.Bitbucket.Git/tools/net/Microsoft.SourceLink.Bitbucket.Git.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.SourceLink.Common/tools/net/Microsoft.SourceLink.Common.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.SourceLink.GitHub/tools/net/Microsoft.SourceLink.GitHub.deps.json /usr/lib64/dotnet/sdk/10.0.103/Sdks/Microsoft.SourceLink.GitLab/tools/net/Microsoft.SourceLink.GitLab.deps.json /usr/lib64/dotnet/sdk/10.0.103/MSBuild.deps.json /usr/lib64/dotnet/sdk/10.0.103/NuGet.CommandLine.XPlat.deps.json /usr/lib64/dotnet/sdk/10.0.103/datacollector.deps.json /usr/lib64/dotnet/sdk/10.0.103/dotnet.deps.json /usr/lib64/dotnet/sdk/10.0.103/redist.deps.json /usr/lib64/dotnet/sdk/10.0.103/testhost.deps.json /usr/lib64/dotnet/sdk/10.0.103/vstest.console.deps.json

I was thinking of the hash in the .deps.json, we sign the .dlls in the Microsoft build which presumably changes the hash which was recorded in .deps.json at build time?

I don't know the answer. This will need more investigation.

Co-authored-by: Alexander Köplinger <alex.koeplinger@outlook.com>

accepted/2026/deterministic-pack-revisited.md

During review, we agreed that the DeterministicTimestamp is a good name.

omajid · 2026-03-09T17:01:06Z

Please feel free to merge if this looks okay now.

accepted/2026/deterministic-pack-revisited.md

nkolev92

One clarifying question about the default.

Worth consider whether we enable this by default in 10.0.300/10.0.400 or 11.0.100.

accepted/2026/deterministic-pack-revisited.md

omajid · 2026-03-12T15:58:23Z

Worth consider whether we enable this by default in 10.0.300/10.0.400 or 11.0.100.

My primary focus is on making the .NET SDK itself reproducible. To do that, I will need to consume this in arcade. I don't think arcade can depend on 10.0.3xx or 10.0.4xx. So I am okay with targeting this to 11.0.100.

- Make summary more focused and explicit about changes. - Drop the technical explanation section.

nkolev92 · 2026-03-12T18:09:11Z

The question that I have is whether it'll be enabled by default.

Does everyone that's installing the .NET 11 SDK now get the new deterministic behavior by default given that it is set it the projects.

That's the part that needs documented/announced and probably the thing that would not meet the 10.0.* bar.

nkolev92

LGTM.

To me 11.0.100 as default make sense, and maybe something we can include in the spec, but not too worried as long as the documentation makes sense. SDKAnalysisLevel is what we can use in this case in the pack targets.

It's also worth considering how we're changing the legacy pack default now that it's auto imported in VS too. This is on the client team though.

akoeplinger · 2026-03-13T13:46:29Z

The question that I have is whether it'll be enabled by default.

That's basically explained in the "Functional explanation" section. With Deterministic=true (default in most projects) some previously random GUID-based file names like <foo.nupkg>/package/services/metadata/core-properties/<GUID>.psmdcp will now be deterministic. This is very low risk.

The slightly more risky change of having deterministic timestamps always requires opting in via DeterministicTimestamp/SOURCE_DATE_EPOCH even for 11.0+

nkolev92 · 2026-03-13T19:45:51Z

Thanks for the clarification.

Honestly, package/services/metadata/core-properties is probably good enough to do even when deterministic is not requested, since we took NuGet/NuGet.Client#6963.

Either way, LGTM

accepted/2026/deterministic-pack-revisited.md

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

accepted/2026/deterministic-pack-revisited.md

nkolev92 · 2026-03-13T20:58:36Z

accepted/2026/deterministic-pack-revisited.md

-   This includes the names of psmdcp files, which are otherwise random and
-   based on a GUID. The names will now be based on a hash that's going to be
-   deterministic.
+   This includes using a single timestamp for all files added to the archive.


This is now suggesting we're making unified timestamp by default, but I don't tihnk that's the case.

This is the plan, indeed: #8601 (comment)

I forgot to spell this out in the doc earlier.

In other words, everything will have the current wall-clock-time as the default timestamp.

With DeterministicTimestamp also set, that will be used as the timestamp instead of the current-wall-clock-time.

So this isn't correct then:

#14785 (comment)

I think Andy's comment is clearer.

IMO this is now confusing since it's not necessarily deterministic if it chooses current time.

We're not aligned in the exact language, but aligned in the UX.

I thinking having a revert makes sense.

If I'm reading it correctly, isn't the only new thing that Deterministic does is unify the timestamps?

Isn't that the switch to revert things?

Basically what if you had a file that was last modified 5 years ago which was preserved before but now when it gets packed it has UtcNow timestamp instead.

Yeah, this was the primary thing. I think @zivkan had the conversations and did some analysis here.

If I'm reading it correctly, isn't the only new thing that Deterministic does is unify the timestamps?

yes but given Deterministic=true is the default since .net core 3.0 and influences other places in the SDK/compiler I'm not sure turning that one off is a good escape hatch.

What if we had:

DeterministicTimestamp=true: default fallback value in the net11 sdk, uses DateTime.UtcNow

DeterministicTimestamp=<explicit value> or SOURCE_DATE_EPOCH set in the environment: optin to the fixed timestamp

DeterministicTimestamp=false: escape hatch to turn the feature off

Added to spec.

I don't mind that.

I was gonna suggest a DeterministicPack option potentially too in case someone wants to decouple it from the general determinism, but I think the timestamp approach is plenty powerful.

I slept on this, but now I am wondering if it might be better to have a few literals other than true and false:

DeterministicTimestamp=wall-clock-time replaces true. It's more explicit about what it's doing

DeterministicTimestamp=file-time to replace false. It's more explicit about the behaviour.

DeterministicTimestamp=<explicit value> or SOURCE_DATE_EPOCH handled as before

Using some fixed literals makes it easier to understand and also allows us to add more knobs if we have to down the line. The values above are just suggestions, I am happy to use another convention/style to make it more consistent with other things.

Is there precedence for this in nuget or .NET ?

accepted/2026/deterministic-pack-revisited.md

MattKotsenas · 2026-03-17T15:41:57Z

accepted/2026/deterministic-pack-revisited.md

+- With `Deterministic=true` by default, support for `Deterministic=false` could
+  be fully dropped, and the code paths simplified.
+
+- Should turning off `Deterministic=true` produce warnings or errors?


Feels like a natural place to start with a BuildCheck and then escalate over time?

Interesting idea, I do wonder if we could get numbers from telemetry how often Build Checks are ran, I feel like that possibility(option) isn't advertised like at all. So what I'm getting at is that it might be used too rarely to be a good guard (should probably still include it but just wanted to highlight the "fact")

Co-authored-by: Matt Kotsenas <51421+MattKotsenas@users.noreply.github.com>

omajid · 2026-03-23T12:45:16Z

Sounds like this is good to merge now?

Make NuGet pack more determinisitic, by default. This makes `Deterministic` property (default = `true`) work again for nuget pack via msbuild. It adds support for `DeterministicTimestamp` property (default = `true`) too. For more details about the properties and the design goals, see: - NuGet/Home#14785 - https://github.com/NuGet/Home/main/accepted/2026/deterministic-pack-revisited.md Fixes: NuGet/Home#8601

Add a design doc for deterministic pack

97b7819

omajid requested a review from a team as a code owner March 3, 2026 20:00

dotnet-policy-service bot added the Community PRs (and linked Issues) created by someone not in the NuGet team label Mar 3, 2026

omajid mentioned this pull request Mar 3, 2026

Re-enable support for deterministic pack NuGet/NuGet.Client#7020

Open

3 tasks

baronfel mentioned this pull request Mar 3, 2026

Opt into NuGet Deterministic Pack mechanism when implemented dotnet/reproducible-builds#78

Open

baronfel reviewed Mar 3, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Show resolved Hide resolved

Frulfump reviewed Mar 3, 2026

View reviewed changes

accepted/2026/deterministic-pack.md Outdated Show resolved Hide resolved

accepted/2026/deterministic-pack-revisited.md Show resolved Hide resolved

accepted/2026/deterministic-pack.md Outdated Show resolved Hide resolved

zivkan previously approved these changes Mar 4, 2026

View reviewed changes

accepted/2026/deterministic-pack.md Outdated Show resolved Hide resolved

accepted/2026/deterministic-pack-revisited.md Show resolved Hide resolved

Update based on feedback

1ad01be

omajid dismissed zivkan’s stale review via 1ad01be March 4, 2026 12:02

Fix typo

7e50f08

omajid mentioned this pull request Mar 4, 2026

RFE: .NET's build is deterministic/reproducible dotnet/source-build#4963

Open

25 tasks

Add a note about the PackageBuilder API changes

e4b8753

akoeplinger reviewed Mar 5, 2026

View reviewed changes

akoeplinger mentioned this pull request Mar 5, 2026

WIP: Set SOURCE_DATE_EPOCH env var during the build dotnet/dotnet#5256

Draft

omajid and others added 2 commits March 5, 2026 12:44

Fix missing closing quote

ed405f0

Co-authored-by: Alexander Köplinger <alex.koeplinger@outlook.com>

Fix typos

3c54ed0

Co-authored-by: Alexander Köplinger <alex.koeplinger@outlook.com>

zivkan reviewed Mar 5, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

omajid added 2 commits March 9, 2026 10:22

Minor updates

cc645bc

Remove unanswered question section

fbfde72

During review, we agreed that the DeterministicTimestamp is a good name.

nkolev92 reviewed Mar 11, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

nkolev92 reviewed Mar 11, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Show resolved Hide resolved

akoeplinger reviewed Mar 12, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

Update based on feedback

5cc96f7

- Make summary more focused and explicit about changes. - Drop the technical explanation section.

nkolev92 previously approved these changes Mar 12, 2026

View reviewed changes

Update based on feedback

2d21d92

omajid dismissed nkolev92’s stale review via 2d21d92 March 13, 2026 14:11

More updates based on feedback and discussions

731fe3f

Frulfump reviewed Mar 13, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

Remove extra 'the'

176947b

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

Frulfump reviewed Mar 13, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

nkolev92 reviewed Mar 13, 2026

View reviewed changes

zivkan previously approved these changes Mar 15, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Show resolved Hide resolved

More adjustments based on feedback

3a63600

omajid dismissed zivkan’s stale review via 3a63600 March 17, 2026 13:25

Frulfump reviewed Mar 17, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

Frulfump reviewed Mar 17, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

Fix extra the's

3af84e2

MattKotsenas reviewed Mar 17, 2026

View reviewed changes

accepted/2026/deterministic-pack-revisited.md Outdated Show resolved Hide resolved

MattKotsenas reviewed Mar 17, 2026

View reviewed changes

nkolev92 previously approved these changes Mar 17, 2026

View reviewed changes

Update accepted/2026/deterministic-pack-revisited.md

28018cb

Co-authored-by: Matt Kotsenas <51421+MattKotsenas@users.noreply.github.com>

omajid dismissed nkolev92’s stale review via 28018cb March 17, 2026 16:48

jeffkl assigned nkolev92 Mar 17, 2026

Update based on feedback

69198d8

nkolev92 approved these changes Mar 19, 2026

View reviewed changes

akoeplinger approved these changes Mar 23, 2026

View reviewed changes

omajid mentioned this pull request Mar 25, 2026

Taking a dependency on a recent nuget version? dotnet/arcade#16623

Open

2 tasks

	embedding a timestamp. Nuget has the concept of a contnet hash, that can
	embedding a timestamp. NuGet has the concept of a content hash, that can

Conversation

omajid commented Mar 3, 2026

Uh oh!

omajid commented Mar 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

omajid commented Mar 4, 2026

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!

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!

Uh oh!

omajid commented Mar 9, 2026

Uh oh!

Uh oh!

nkolev92 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

omajid commented Mar 12, 2026

Uh oh!

nkolev92 commented Mar 12, 2026

Uh oh!

nkolev92 left a comment

Choose a reason for hiding this comment

Uh oh!

akoeplinger commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nkolev92 commented Mar 13, 2026

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!

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!

omajid Mar 27, 2026 • 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!

Uh oh!

Choose a reason for hiding this comment

akoeplinger commented Mar 13, 2026 •

edited

Loading

omajid Mar 27, 2026 •

edited

Loading

Frulfump Mar 17, 2026 •

edited

Loading