dotnet-package-add(1)

okay bestie, welcome to the dotnet-package-add(1) page from the .NET Documentation manual set. this is the whole thing, nothing skipped, everything slayed. 💖

This article applies to: ✔️ .NET 6 SDK and later versions

---

✨ NAME ✨

dotnet-package-add — adds or updates a package reference in a project file. 🎀

🫶 real talk, read this first: if you're on .NET 9 SDK or earlier, use the "verb first" form (dotnet-add-package) instead. the "noun first" form was introduced in .NET 10. more deets live in More consistent command order.

---

🌈 SYNOPSIS 🌈

dotnet package add <PACKAGE_NAME>
    [-f|--framework <FRAMEWORK>] [--interactive] [--project <PROJECT>]
    [-n|--no-restore] [--package-directory <PACKAGE_DIRECTORY>]
    [--prerelease] [-s|--source <SOURCE>] [-v|--version <VERSION>]

dotnet package add -h|--help

---

💜 DESCRIPTION 💜

the dotnet package add command is the convenient lil option for adding or updating a package reference in a project file. here's the tea: when you run it, there's a compatibility check to make sure the package is compatible with the frameworks in the project.

• if the check passes and the package isn't referenced in the project file, a <PackageReference> element gets added to the project file. ✨
• if the check passes and the package is already referenced in the project file, the <PackageReference> element gets updated to the latest compatible version. 💅

after the project file is updated, dotnet restore is run. no cap.

for example, adding Microsoft.EntityFrameworkCore to ToDo.csproj produces output similar to the following example:

Determining projects to restore...
Writing C:\Users\username\AppData\Local\Temp\tmp24A8.tmp
info : Adding PackageReference for package 'Microsoft.EntityFrameworkCore' into project 'C:\ToDo\ToDo.csproj'.
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/index.json
info :   GET https://pkgs.dev.azure.com/dnceng/9ee6d478-d288-47f7-aacc-f6e6d082ae6d/_packaging/516521bf-6417-457e-9a9c-0a4bdfde03e7/nuget/v3/registrations2-semver2/microsoft.entityframeworkcore/index.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/0.0.1-alpha/3.1.3.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/3.1.4/7.0.0-preview.2.22153.1.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/7.0.0-preview.3.22175.1/7.0.0-preview.3.22175.1.json
info :   NotFound https://pkgs.dev.azure.com/dnceng/9ee6d478-d288-47f7-aacc-f6e6d082ae6d/_packaging/516521bf-6417-457e-9a9c-0a4bdfde03e7/nuget/v3/registrations2-semver2/microsoft.entityframeworkcore/index.json 257ms
info : Restoring packages for C:\ToDo\ToDo.csproj...
info : Package 'Microsoft.EntityFrameworkCore' is compatible with all the specified frameworks in project 'C:\ToDo\ToDo.csproj'.
info : PackageReference for package 'Microsoft.EntityFrameworkCore' version '6.0.4' added to file 'C:\ToDo\ToDo.csproj'.
info : Writing assets file to disk. Path: C:\ToDo\obj\project.assets.json
log  : Restored C:\ToDo\ToDo.csproj (in 171 ms).

the ToDo.csproj file now contains a <PackageReference> element for the referenced package. iconic.

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

if the project is onboarded onto Central Package Management (CPM) (https://devblogs.microsoft.com/nuget/introducing-central-package-management/) the <PackageVersion> element in the Directory.Packages.props file is added/updated and the <PackageReference> element is added to the project file. 🦋

the following scenarios are currently supported. these examples assume that the latest version of Microsoft.EntityFrameworkCore is 6.0.4. additional scenarios related to CPM are documented in this design spec (https://github.com/NuGet/Home/pull/11915).

🌸 Scenario 1 🌸

<PackageReference> does not exist in the project file, <PackageVersion> element does not exist in the Directory.Packages.props file, and the version argument is not passed from the commandline.

CLI command that is executed: dotnet package add Microsoft.EntityFrameworkCore --project ToDo.csproj

the <PackageVersion> element is added to the Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

the <PackageReference> element is added to the project file.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

🌸 Scenario 2 🌸

<PackageReference> does not exist in the project file, <PackageVersion> element does not exist in the Directory.Packages.props file, and the version argument is passed from the commandline.

CLI command that is executed: dotnet package add Microsoft.EntityFrameworkCore --version 5.0.4 --project ToDo.csproj

the <PackageVersion> element is added to the Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="5.0.4" />

the <PackageReference> element is added to the project file.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

🌸 Scenario 3 🌸

<PackageReference> does not exist in the project file, <PackageVersion> element does exist in the Directory.Packages.props file, and the version argument is not passed from the commandline.

CLI command that is executed: dotnet package add Microsoft.EntityFrameworkCore --project ToDo.csproj

the <PackageVersion> element is added to the Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

the <PackageReference> element is added to the project file.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

🌸 Scenario 4 🌸

<PackageReference> does not exist in the project file, <PackageVersion> element does exist in the Directory.Packages.props file, and the version argument is passed from the commandline.

CLI command that is executed: dotnet package add Microsoft.EntityFrameworkCore --version 5.0.4 --project ToDo.csproj

the <PackageVersion> element is added to the Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="5.0.4" />

the <PackageReference> element is added to the project file.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

---

🧚 Implicit restore 🧚

you do not have to run dotnet restore, bestie, because it's run implicitly by all commands that require a restore to occur, such as dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish, and dotnet pack. to disable implicit restore, use the --no-restore option. 💅

the dotnet restore command is still useful in certain scenarios where explicitly restoring makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control when the restore occurs.

for information about how to manage NuGet feeds, see the dotnet restore documentation.

---

🎀 ARGUMENTS 🎀

• PROJECT — specifies the project file. if not specified, the command searches the current directory for one. 🔍
• PACKAGE_NAME — the package reference to add.

---

✨ OPTIONS ✨

• -f|--framework <FRAMEWORK> — adds a package reference only when targeting a specific framework.
• -?|-h|--help — prints out a description of how to use the command. 🫶
• --interactive — allows the command to stop and wait for user input or action. for example, to complete authentication.
• -n|--no-restore — adds a package reference without performing a restore preview and compatibility check.
• --package-directory <PACKAGE_DIRECTORY> — the directory where to restore the packages. the default package restore location is %userprofile%\.nuget\packages on Windows and ~/.nuget/packages on macOS and Linux. for more information, see Managing the global packages, cache, and temp folders in NuGet.
• --prerelease — allows prerelease packages to be installed.
• -s|--source <SOURCE> — the URI of the NuGet package source to use during the restore operation.
• -v|--version <VERSION> — version of the package. see NuGet package versioning.

---

🔥 EXAMPLES 🔥

1. add Microsoft.EntityFrameworkCore NuGet package to a project:

dotnet package add Microsoft.EntityFrameworkCore

2. add a specific version of a package to a project:

dotnet package add Microsoft.Azure.DocumentDB.Core -v 1.0.0 --project ToDo.csproj

3. add a package using a specific NuGet source:

dotnet package add Microsoft.AspNetCore.StaticFiles -s https://dotnet.myget.org/F/dotnet-core/api/v3/index.json

---

💖 SEE ALSO 💖

• Managing the global packages, cache, and temp folders in NuGet
• NuGet package versioning

---

and that's the whole page, periodt. this beauty is from 2025-10-30, and it lives in the manual as dotnet-package-add(1) 💅✨ — go add some packages, main character. 👑