A nuget.config (also written NuGet.Config or
NuGet.config; the name is not case-sensitive) tells NuGet where to find packages
and how to behave: the package sources, their credentials, which sources may supply which
packages, the folders packages are kept in, and whom to trust. NuGet reads every such file from
the project’s folder upward, and then the user’s and the machine’s, and merges them. It is XML
with a configuration root, no namespace, and one element for each section.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="local" value="./packages-local" />
</packageSources>
<packageSourceMapping>
<packageSource key="nuget.org"><package pattern="*" /></packageSource>
<packageSource key="local"><package pattern="Contoso.*" /></packageSource>
</packageSourceMapping>
<config>
<add key="globalPackagesFolder" value="./pkgs" />
</config>
</configuration>Contoso.* packages are taken from the local one.Entries
Most sections hold add entries, each a key and a
value, and may hold clear (forget what earlier files said about this
section) and remove (forget one key). A later file’s entry for the same key
replaces an earlier one. Setting names are not case-sensitive.
| Element | Attributes | Meaning |
|---|---|---|
add | key, value | Sets the entry; a repeated key in one section is a note, the later wins. |
remove | key | Drops the entry another file set. |
clear | Drops every entry the earlier files gave in this section; write it first. |
Sections
| Section | Holds |
|---|---|
config | Miscellaneous keys, listed below. |
bindingRedirects | skip: whether to skip automatic binding redirects on install (default false). |
packageRestore | enabled: whether automatic restore may run; automatic: whether to check for missing packages during a build. |
solution | disableSourceControlIntegration: ignore the packages folder in source control; only read from a file in a solution’s folder. |
packageSources | The known package sources: below. |
packageSourceCredentials | Credentials of sources: below. |
disabledPackageSources | Sources that are off: add key="name" value="true". A source not listed is enabled. |
activePackageSource | The current source or All (NuGet 2.x; deprecated). |
apikeys | API keys for push sources, by source address, as nuget setapikey stores them (encrypted on Windows). |
auditSources | The sources NuGet Audit asks about vulnerabilities; the same attributes as packageSources. Without it, the package sources are used. |
clientCertificates | Client certificates for HTTPS sources: below. |
trustedSigners | Trusted package signers: below. |
fallbackPackageFolders | Read-only package folders with the layout of the global packages folder, searched before the sources (NuGet 3.5 and later): add entries whose value is a folder. |
packageSourceMapping | Which sources may supply which packages: below. |
minPublishAgeExceptions | Packages exempt from the minimum publish age: package entries with a pattern. The nearest file that has the section replaces the whole list. |
packageManagement | format: 1 PackageReference, 0 packages.config; disabled: whether to hide the prompt to choose. |
The config section
| Key | Value |
|---|---|
defaultPushSource | The source used by a push when none is given. |
dependencyVersion | packages.config only: the default DependencyVersion for install, restore and update. |
globalPackagesFolder | The global packages folder (default %userprofile%\.nuget\packages or ~/.nuget/packages); PackageReference only; a relative path is allowed in a project’s file. |
repositoryPath | packages.config only: where packages are installed instead of $(SolutionDir)/packages. |
http_proxy, http_proxy.user, http_proxy.password, no_proxy | Proxy settings; the password is stored encrypted and cannot be typed in. |
maxHttpRequestsPerSource | The most parallel requests to a source. |
signatureValidationMode | accept (default) or require: how package signatures are checked on install and restore. |
updatePackageLastAccessTime | When true, restore touches the .nupkg.metadata file of each package it uses. |
Package sources
In packageSources (and auditSources) each add has
key, the name, and value, an address or a folder. Order is ignored by
restore and by PackageReference projects.
| Attribute | Meaning |
|---|---|
protocolVersion | The server protocol: 3 for a V3 service index (an address ending in .json); the default is 2 for other addresses. |
allowInsecureConnections | true stops the warning for an http source. |
disableTLSCertificateValidation | true ignores certificate errors of an HTTPS source. |
minPublishAgeHours | The hours since publication before a version may be chosen automatically. |
Credentials
Inside packageSourceCredentials there is one element per source, named after
the source’s key with characters XML does not allow in a name written as
_xXXXX_ (a space is _x0020_). Each holds
add entries:
| Key | Value |
|---|---|
Username | The user name, in plain text (environment variables may be used). |
Password | The encrypted password; encryption is Windows only and the file can be decrypted only by the same user on the same machine. |
ClearTextPassword | The password in clear text (discouraged; environment variables may be used). |
ValidAuthenticationTypes | A comma-separated list of authentication types, for example basic when a server advertises NTLM or Negotiate but needs Basic. |
Package source mapping
packageSourceMapping holds packageSource elements, each with a
key that matches a source’s key exactly, and inside it package
elements with a pattern: a package id, or a prefix ending in *
(* alone is every package). Patterns are case-insensitive, and for each package the
source with the longest matching pattern is the one used. It filters the download path of restore,
install and update; commands that only ask sources about packages ask all of them.
Client certificates
clientCertificates holds at most one certificate element for each source, and
clear.
| Element | Attributes |
|---|---|
fileCert | packageSource (required, the source’s key), path (required; a PKCS #12 file), password or clearTextPassword (not both) |
storeCert | packageSource (required), findValue (required), storeLocation (CurrentUser default, LocalMachine), storeName (My default, AddressBook, AuthRoot, CertificateAuthority, Disallowed, Root, TrustedPeople, TrustedPublisher), findBy (an X509FindType without FindBy; Thumbprint default) |
Trusted signers
Each trusted signer is an author or a repository element with a
name, holding certificate elements with fingerprint,
hashAlgorithm (SHA256, SHA384 or SHA512) and
allowUntrustedRoot. A repository also has a
serviceIndex (an https address) and may have an
owners child: a semicolon-separated list of the owners trusted from it. The list may
not be empty when signatureValidationMode is require.
Environment variables
A value may hold %NAME%, which NuGet replaces with the environment variable,
on every platform; $NAME is not recognised. A variable that is not set is left as
written. / works as a separator everywhere, \ only on Windows.
In the explorer
A file named nuget.config whose root is configuration opens with
each section, entry and attribute explained in the tree, and tabs for the sources
(with their credential keys; passwords and keys are never shown), the settings, the source
mapping and the trusted signers. A .config file that is an application or web
configuration is not claimed: it needs a NuGet section or the name nuget.config.
Not described
Known, not yet covered
- Reference: the order in which NuGet merges the files of a folder tree, the user and the machine, and the commands that edit the file (
nuget sources,dotnet nuget); they are in NuGet’s documentation.
Sources
Microsoft Learn (the NuGet documentation), nuget.config reference, read from its open-source repository.