NUPKG file format: the .nuspec manifest

Every package contains its .nuspec, an XML manifest used both to build the package and to describe it to consumers. This page follows Microsoft’s “.nuspec File Reference for NuGet”. Element names are case-sensitive. The root is package in the namespace http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd (other years, such as 2012/06, appear in examples). A nuspec.xsd exists in the NuGet.Client repository, but no schema has been published for validation and none matches a particular NuGet version.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata minClientVersion="3.3">
    <id>sample</id>
    <version>1.2.3</version>
    <authors>Kim Abercrombie, Franck Halmaert</authors>
    <description>Sample exists only to show a sample .nuspec file.</description>
    <license type="expression">MIT</license>
  </metadata>
  <files> … </files>
</package>

The general form, based on Microsoft’s examples.

Required metadata

Element	Meaning	nuget.org limit
`id`	Package identifier, case-insensitive, unique in the gallery; no spaces or characters invalid in a URL; generally follows .NET namespace rules.	100
`version`	`major.minor.patch`, optionally with a pre-release suffix.	64
`description`	Description for display.	4000
`authors`	Comma-separated authors (ignored by nuget.org for ownership).	—

Optional metadata

Element	Since	Meaning
`owners`		Deprecated; comma-separated owners, ignored by nuget.org.
`projectUrl`		The package’s home page (limit 4000).
`licenseUrl`		Deprecated in favour of `license` (limit 4000).
`license`	NuGet 4.9.0	`type="expression"`: an SPDX licence expression such as `MIT` or `BSD-2-Clause OR MIT`; `type="file"`: path of a `.txt` or `.md` licence file in the package.
`iconUrl`		Deprecated: URL of a 128×128 image with transparent background (limit 4000).
`icon`	NuGet 5.3.0	Path of a JPEG or PNG in the package, up to 1 MB; 128×128 recommended.
`readme`	NuGet 5.10.0 preview 2	Path of a Markdown readme in the package.
`requireLicenseAcceptance`		Boolean: the client must ask the user to accept the licence.
`developmentDependency`	2.8	Boolean: a development-only dependency, not passed on as a dependency of other packages; with PackageReference (4.8+) its compile-time assets are excluded.
`summary`		Being deprecated; short description (limit 4000).
`releaseNotes`	1.5	Changes in this release (limit 35,000).
`copyright`	1.5	Copyright details (limit 4000).
`language`		Locale ID of the package.
`tags`		Space-separated tags (limit 4000).
`serviceable`	3.3	For NuGet’s internal use only.
`repository`	4.0 / 4.6	Attributes `type` and `url` (4.0), `branch` and `commit` (4.6): the source repository that built the package (type limit 100, url 4000).
`title`		Human-friendly title; not shown by nuget.org or Visual Studio (limit 256).
`packageTypes`	3.5	`<packageType name="…" version="…"/>` elements, when the package is not an ordinary dependency package.
`dependencies`		Dependencies.
`frameworkAssemblies`	1.2	Framework assembly references.
`references`	1.5	Explicit assembly references.
`contentFiles`	3.3	Content files for PackageReference projects.
`frameworkReferences`	5.1	Shared framework references.

Attribute of metadata: minClientVersion, the minimum NuGet client that may install the package (for example 2.8 when using developmentDependency, 3.3 for contentFiles). Clients older than 2.5 do not know it and refuse the package.

Licence expressions

license-id           = <SPDX short-form licence identifier>
license-exception-id = <SPDX short-form licence exception identifier>
simple-expression    = license-id / license-id "+"
compound-expression  = 1*1(simple-expression /
                       simple-expression "WITH" license-exception-id /
                       compound-expression "AND" compound-expression /
                       compound-expression "OR" compound-expression ) /
                       "(" compound-expression ")" )
license-expression   = 1*1(simple-expression / compound-expression / UNLICENSED)

The ABNF in Microsoft’s reference. nuget.org accepts only OSI- or FSF-approved licences.

Dependencies

`dependency` attribute	Meaning
`id`	Required. The package ID (limit 128).
`version`	Required. A version range, such as `1.1.0` (1.1.0 or later) or `[1,2)`; floating versions are not allowed (limit 256).
`include`	Comma-separated include/exclude tags to take from the dependency; default `all`.
`exclude`	Tags to leave out; default `build,analyzers`; content is always excluded. Wins over `include`.

Tag	Folders of the dependency affected
`contentFiles`	Content
`runtime`	Runtime, Resources and FrameworkAssemblies
`compile`	`lib`
`build`	`build` (MSBuild props and targets)
`native`	`native`
`none`	No folders
`all`	All folders

Groups (NuGet 2.0+): instead of a flat list, dependencies may hold <group targetFramework="…"> elements, each with its own dependencies; a group without targetFramework is the fallback. Groups and a flat list cannot be mixed.

Explicit assembly references

<references> (for packages.config projects) names the assemblies in lib to reference: <reference file="xunit.dll"/>. It may instead hold <group targetFramework="…"> elements (not mixed with a flat list). Without it, every assembly in lib is referenced.

Framework assembly references

<frameworkAssembly> names a .NET Framework assembly from the global assembly cache to reference: assemblyName (required, fully qualified) and targetFramework (optional; all frameworks when absent).

Framework reference groups

NuGet 5.1+, PackageReference only: <frameworkReferences> holds <group targetFramework="…"> elements (the attribute is required), each with <frameworkReference name="…"/> naming a shared framework such as Microsoft.WindowsDesktop.App.WPF.

files

A sibling of metadata listing what to pack, one <file> per entry:

Attribute	Meaning
`src`	Files to include, relative to the `.nuspec` unless absolute; `` and recursive `*` wildcards.
`target`	Folder in the package, starting with `lib`, `content`, `build` or `tools`. If its extension matches the source’s it is taken as a file name, otherwise as a folder.
`exclude`	Semicolon-separated files or patterns to leave out.

Assemblies named *.resources.dll are treated as satellite assemblies and not referenced.

contentFiles

Inside metadata, a list of <files> elements (applied top to bottom; the topmost wins on conflict) for content in the package’s contentFiles/language/tfm/… folders, where language is cs, vb, fs, any or a lower-case project language, and tfm a target framework moniker. An empty folder can hold _._ to provide nothing for that combination.

Attribute	Meaning
`include`	Required. Files relative to `contentFiles`, with wildcards.
`exclude`	Semicolon-separated patterns to leave out.
`buildAction`	MSBuild build action: `Content`, `None`, `EmbeddedResource`, `Compile` (default)…
`copyToOutput`	Boolean, default false: copy to the build or publish output.
`flatten`	Boolean, default false: copy into one folder instead of keeping the structure (only with `copyToOutput`).

Replacement tokens

When nuget pack is run on a project file, $-delimited tokens in metadata and files are replaced (other tokens come from -properties; except for $configuration$ , project values win):

Token	Value
$id$	AssemblyName from the project file
$version$	AssemblyInformationalVersion, else AssemblyVersion
$author$	AssemblyCompany
$title$	AssemblyTitle
$description$	AssemblyDescription
$copyright$	AssemblyCopyright
$configuration$	Build configuration, default Debug

Sources

Microsoft Learn, NuGet: “.nuspec File Reference for NuGet” (every element, attribute, limit, tag and token on this page). Not covered here: the Open Packaging Conventions parts ([Content_Types].xml, _rels/.rels, the .psmdcp core properties) and the .signature.p7s package signature, which this reference does not describe.

.NUPKG File Format – The .nuspec manifest