Format:NuGet package
| Magic | PK\x03\x04 (ZIP) |
|---|---|
| Extensions | .nupkg, .snupkg, .symbols.nupkg |
| On this wiki | Facts · Code · Notes · Topics |
NuGet package (.nupkg): an OPC ZIP with a .nuspec manifest, [Content_Types].xml and _rels, payload under lib/<tfm>/, ref/, runtimes/, build/, tools/ and others, and for signed packages a .signature.p7s entry; install.ps1/init.ps1 under tools/ are PowerShell scripts run by Visual Studio package managers, MSBuild build/ files run at build.
A .nupkg is an Open Packaging Conventions ZIP archive, so it contains [Content_Types].xml, a _rels/.rels relationship part and a package/services/metadata/core-properties/<guid>.psmdcp core-properties part besides the real package files (Unverified: the exact psmdcp path; the extractor only skips files with the .psmdcp extension). The only mandatory content is a .nuspec at the archive root; its file name is <id>.nuspec.
Folders
NuGet.Client PackagingConstants.Folders lists the known top-level folders: content, contentFiles, build, buildCrossTargeting, buildTransitive, tools, lib, native, runtimes, ref, analyzers, src. Under lib/, ref/ and similar the next level is a target framework moniker such as net8.0 or netstandard2.0 (any and agnostic are special names). A file named _._ stands for an empty folder because OPC cannot store one. lib/ holds the assemblies that are referenced and run; ref/ the reference assemblies; runtimes/<rid>/lib and runtimes/<rid>/native RID-specific code; analyzers/ Roslyn analyzers that run inside the compiler.
Where code runs
build/*.propsand*.targets(andbuildTransitive) are imported into the consuming project's MSBuild build; Unverified: targets can run tasks and arbitrary commands at build time (general MSBuild behaviour, not read here).tools/init.ps1,tools/install.ps1andtools/uninstall.ps1are PowerShell scripts: NuGet.Client defines these names inPowerShellScripts.cs. They run only in the Visual Studio Package Manager / packages.config flow, not for PackageReference restores ordotnet restore(Unverified: this restriction is the documented behaviour; confirm in the NuGet docs, the source read here only defines the file names).- Unverified: analyzers and source generators in
analyzers/run in the compiler process.
Signing
A signed package carries an extra entry .signature.p7s (a CMS/PKCS#7 signature, see Format:ASN.1 DER and BER). Signing specification V1 allows SHA-256, SHA-384 and SHA-512 digests, RSA signatures with those hashes and RSA keys of at least 2048 bits.
Client cache layout
When extracting into a global packages folder, the extractor skips .rels, [Content_Types].xml, *.psmdcp, the root .nuspec and .nupkg copies and the .nupkg.metadata file, and Unverified: writes <id>.<version>.nupkg.sha512 (base64 SHA-512 of the package) and .nupkg.metadata next to the unpacked files (only the extension constants and the skip rule were read).
Code & repositories
- https://github.com/NuGet/NuGet.Client @
4c4510d29a64fcbcba6360e29c3a1e8288a87f9f· license: Apache-2.0 (declared by the contributor for the files used; GitHub reports Apache-2.0 (read from LICENSE.txt; GitHub's API was busy) for the repository)
NuGet client: NuGet.Packaging constants, extractor and signing specification V1.
Tested on: source read, not run · checked 2026-10-19
See also
Technique:Install-time code execution in package archives, Format:.NET metadata (ECMA-335) for the assemblies under lib/.