/flags/nuget/dotnet-restore-source
dotnet restore --source (-s): restore from a specific NuGet feed or folder
- tool
- NuGet
- command
- dotnet restore
- flag
- -s, --source SOURCE
- default
- the sources from nuget.config (nuget.org on a default install)
dotnet restore --source ./feed (short -s) restores packages only from the given source: a feed URL such as https://api.nuget.org/v3/index.json, a private feed, or a plain folder containing .nupkg files. The sources configured in nuget.config are ignored for that call, so a package that exists only on nuget.org then fails with NU1101. Repeat -s to combine sources. The option exists on dotnet restore, dotnet build, dotnet add package and dotnet tool install as well.
A local folder as the only source
A library is packed into feed/; the app references it and Newtonsoft.Json:
dotnet new classlib -o Demo.Lib > /dev/null
dotnet pack Demo.Lib -o feed -p:PackageVersion=1.0.0 -v q -nologo > /dev/null 2>&1
ls feed
FEED="$PWD/feed"
dotnet new console -o app --no-restore > /dev/null && cd app
sed -i 's#</Project># <ItemGroup>\n <PackageReference Include="Demo.Lib" Version="1.0.0" />\n <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />\n </ItemGroup>\n</Project>#' app.csproj
echo "--- dotnet restore -s $FEED"
dotnet restore -s "$FEED" 2>&1 | grep -o "error NU1101: [^[]*" | sed -E 's/ +$//'
echo "--- dotnet restore -s https://api.nuget.org/v3/index.json -s $FEED"
dotnet restore -s https://api.nuget.org/v3/index.json -s "$FEED" -v q > /dev/null; echo "exit: $?"Output
Demo.Lib.1.0.0.nupkg --- dotnet restore -s /tmp/work/feed error NU1101: Unable to find package Newtonsoft.Json. No packages exist with this id in source(s): /tmp/work/feed --- dotnet restore -s https://api.nuget.org/v3/index.json -s /tmp/work/feed exit: 0
With only the folder, Demo.Lib is found but Newtonsoft.Json is not, and NuGet reports NU1101 naming the source it searched. Adding nuget.org as a second -s restores both.
Ways to choose sources
| Method | Scope |
|---|---|
| -s URL_OR_PATH (repeatable) | This command only; replaces nuget.config sources |
| nuget.config packageSources | Every restore under that folder |
| dotnet nuget add source PATH -n NAME | Writes a source into nuget.config |
| RestoreSources MSBuild property | Project-level list, semicolon-separated |
| RestoreAdditionalProjectSources | Adds sources without replacing the configured ones |
| packageSourceMapping in nuget.config | Decide which package IDs may come from which source |
The configuration file approach is covered in nuget.config package sources.
Typical uses
- Testing a package before publishing:
dotnet pack -o ./feed, thendotnet add package Demo.Lib -s ./feedin a test app. See dotnet pack. - Offline builds: a folder of pre-downloaded packages as the only source.
- Isolating a failing feed: restore with
-s https://api.nuget.org/v3/index.jsonto see whether an error such as NU1301 comes from a private feed.
Pitfalls
- NuGet caches packages in the global packages folder. A package that was restored once from nuget.org is found there even when
-spoints elsewhere, so a test with a local feed can pass for the wrong reason; clear the cache or use a freshNUGET_PACKAGESfolder to test properly. - Folder feeds are scanned file by file, so large flat folders are slow. The
nuget addcommand of nuget.exe creates the faster hierarchical layout (id/version/);dotnet nuget pushto a folder just copies the file. - Credentials for private feeds belong in
nuget.config(packageSourceCredentials) or a credential provider, never on the command line.
FAQ
Does --source add a feed or replace the configured ones?
It replaces them for that restore: only the sources given with -s are used, and the sources in nuget.config are ignored. Repeat -s to use several, including nuget.org if you still need it.
Can --source point to a folder?
Yes. A local or network folder with .nupkg files is a valid source, for example -s ./packages or the UNC path of a network share. That is the simplest way to test a package before publishing it.
How do I make a source permanent?
Add it to nuget.config with dotnet nuget add source PATH_OR_URL -n NAME, or edit the packageSources section. Then a plain dotnet restore uses it.