Package source mapping filters which feed NuGet downloads from during restore, install and update. It does not filter metadata lookups such as dotnet list package or dotnet add package, it is skipped for packages already in the global packages folder, and it cannot judge whether a package is trustworthy. These are documented limits.
Gap 1: metadata queries
Microsoft's documentation says mapping applies when NuGet downloads packages. Commands that look up package information, including adding a package and listing outdated, deprecated or vulnerable packages, send the requested IDs to all configured sources. That includes public ones.
Why it matters: if you have a private package named Contoso.Billing, a metadata command may ask nuget.org whether such a package exists. The query itself reveals the name. Tracking issues for this are linked from the docs.
Gap 2: the global packages folder
When a requested package is already in the global packages folder, no source lookup happens and mappings are ignored. A package that arrived before you enabled mapping, or from a different checkout, will be reused.
Mitigations from the docs:
- Declare a repository specific global packages folder.
- Clear the global packages folder with the locals command when you onboard.
- Restore again and fix any package that does not match a mapping.
Gap 3: older tooling
Older tools ignore the mapping configuration. The feature needs NuGet 6.0 or later, the .NET SDK 6.0.100 or later, or nuget.exe 6.0.0 or later. A build agent with an old SDK would restore without it.
Gap 4: it does not vet content
Mapping tells NuGet where a package ID may come from. It says nothing about whether the package on that feed is malicious, vulnerable or unmaintained. If you map everything to nuget.org with the star pattern, a malicious package published there is still allowed.
Gap 5: configuration drift
Settings follow normal nuget.config precedence, so an extra file elsewhere can change behavior. There are also no dotnet or nuget.exe commands to manage mappings, so edits are manual or through Visual Studio.
What to pair it with
| Risk | Pair mapping with |
|---|---|
| Malicious or typosquatted package | Review of new dependencies, signature policy, prefix reservation signals |
| Vulnerable package | NuGet Audit with transitive checking, and a scanner |
| Unpredictable restores | Lock file and locked mode in CI |
| Name leakage in queries | Keep internal names unlikely to collide, use a single upstreaming feed |
| Stale cache | Clean or repository specific package folders in CI |
A short checklist
- One repository nuget.config with clear elements.
- Mapping for every package ID, including transitive ones.
- A CI agent that starts from a clean cache.
- Current SDK versions everywhere.
- Review changes to nuget.config like code.
Try it yourself
Click through it at your own pace, or open it full screen. Mapping needs a full package list, and this is what that list looks like.
Safeguard's dependency scanning and SBOM output cover the content side that mapping leaves open, and a free scan is a place to start.
Quick check
Does package source mapping hide my private package names from nuget.org?
Not for metadata commands. Those send package IDs to every configured source.
Why did mapping not stop a package from an unexpected source?
It may already have been in the global packages folder, where mappings are not consulted.
Sources
- Package Source Mapping, Microsoft Learn
- Best practices for a secure software supply chain, Microsoft Learn
Last reviewed: 19 October 2026.
