Ubuntu Manpage: This article applies to: ✔️ .NET Core 3.1 SDK and later versions

Provided by: dotnet-host-8.0_8.0.18-0ubuntu1~24.04.1_amd64

dotnet publish

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

NAME

       dotnet-publish  -  Publishes the application and its dependencies to a folder for deployment to a hosting
       system.

SYNOPSIS

              dotnet publish [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
                  [-c|--configuration <CONFIGURATION>] [--disable-build-servers]
                  [-f|--framework <FRAMEWORK>] [--force] [--interactive]
                  [--manifest <PATH_TO_MANIFEST_FILE>] [--no-build] [--no-dependencies]
                  [--no-restore] [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
                  [--os <OS>] [-r|--runtime <RUNTIME_IDENTIFIER>]
                  [--sc|--self-contained [true|false]] [--no-self-contained]
                  [-s|--source <SOURCE>] [--use-current-runtime, --ucr [true|false]]
                  [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]

              dotnet publish -h|--help

DESCRIPTION

dotnet publish compiles the application, reads through its dependencies specified in the project file,
and publishes the resulting set of files to a directory. The output includes the following assets:

• Intermediate Language (IL) code in an assembly with a dll extension.

• A .deps.json file that includes all of the dependencies of the project.

• A .runtimeconfig.json file that specifies the shared runtime that the application expects, as well as
other configuration options for the runtime (for example, garbage collection type).

• The application’s dependencies, which are copied from the NuGet cache into the output folder.

The dotnet publish command’s output is ready for deployment to a hosting system (for example, a server,
PC, Mac, laptop) for execution. It’s the only officially supported way to prepare the application for
deployment. Depending on the type of deployment that the project specifies, the hosting system may or
may not have the .NET shared runtime installed on it. For more information, see Publish .NET apps with
the .NET CLI.

Implicit restore
You don’t have to run dotnet restore 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 explicit‐
ly control when the restore occurs.

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

MSBuild
The dotnet publish command calls MSBuild, which invokes the Publish target. If the IsPublishable proper‐
ty is set to false for a particular project, the Publish target can’t be invoked, and the dotnet publish
command only runs the implicit dotnet restore on the project.

Any parameters passed to dotnet publish are passed to MSBuild. The -c and -o parameters map to MSBuild’s
Configuration and PublishDir properties, respectively.

The dotnet publish command accepts MSBuild options, such as -p for setting properties and -l to define a
logger. For example, you can set an MSBuild property by using the format: -p:<NAME>=<VALUE>.

.pubxml files
You can also set publish-related properties by referring to a .pubxml file. For example:

dotnet publish -p:PublishProfile=FolderProfile

The preceding example uses the FolderProfile.pubxml file that is found in the <project_folder>/Proper‐
ties/PublishProfiles folder. If you specify a path and file extension when setting the PublishProfile
property, they’re ignored. MSBuild by default looks in the Properties/PublishProfiles folder and assumes
the pubxml file extension. To specify the path and filename including extension, set the PublishProfile‐
FullPath property instead of the PublishProfile property.

In the .pubxml file:

• PublishUrl is used by Visual Studio to denote the Publish target.

• PublishDir is used by the CLI to denote the Publish target.

If you want the scenario to work in all places, you can initialize both these properties to the same val‐
ue in the .pubxml file. When GitHub issue dotnet/sdk#20931 (https://github.com/dotnet/sdk/issues/20931)
is resolved, only one of these properties will need to be set.

Some properties in the .pubxml file are honored only by Visual Studio and have no effect on dotnet pub‐
lish. We’re working to bring the CLI more into alignment with Visual Studio’s behavior. But some prop‐
erties will never be used by the CLI. The CLI and Visual Studio both do the packaging aspect of publish‐
ing, and dotnet/sdk#29817 (https://github.com/dotnet/sdk/pull/29817) plans to add support for more prop‐
erties related to that. But the CLI doesn’t do the deployment automation aspect of publishing, and prop‐
erties related to that aren’t supported. The most notable .pubxml properties that aren’t supported by
dotnet publish are the following ones that impact the build:

• LastUsedBuildConfiguration

• Configuration

• Platform

• LastUsedPlatform

• TargetFramework

• TargetFrameworks

• RuntimeIdentifier

• RuntimeIdentifiers

MSBuild properties
The following MSBuild properties change the output of dotnet publish.

• PublishReadyToRun

Compiles application assemblies as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) com‐
pilation. For more information, see ReadyToRun images.

To see warnings about missing dependencies that could cause runtime failures, use PublishReadyToRun‐
ShowWarnings=true.

We recommend that you specify PublishReadyToRun in a publish profile rather than on the command line.

• PublishSingleFile

Packages the app into a platform-specific single-file executable. For more information about single-
file publishing, see the single-file bundler design document (https://github.com/dotnet/de‐
signs/blob/main/accepted/2020/single-file/design.md).

We recommend that you specify this option in the project file rather than on the command line.

• PublishTrimmed

Trims unused libraries to reduce the deployment size of an app when publishing a self-contained exe‐
cutable. For more information, see Trim self-contained deployments and executables. Available since
.NET 6 SDK.

We recommend that you specify this option in the project file rather than on the command line.

For more information, see the following resources:

• MSBuild command-line reference

• Visual Studio publish profiles (.pubxml) for ASP.NET Core app deployment

• dotnet msbuild

Workload manifest downloads
When you run this command, it initiates an asynchronous background download of advertising manifests for
workloads. If the download is still running when this command finishes, the download is stopped. For
more information, see Advertising manifests.

ARGUMENTS

       • PROJECT|SOLUTION

         The project or solution to publish.

         • PROJECT is the path and filename of a C#, F#, or Visual Basic project file, or the path to a directo‐
           ry  that  contains a C#, F#, or Visual Basic project file.  If the directory is not specified, it de‐
           faults to the current directory.

         • SOLUTION is the path and filename of a solution file (.sln extension), or the  path  to  a  directory
           that  contains a solution file.  If the directory is not specified, it defaults to the current direc‐
           tory.

OPTIONS

• -a|--arch <ARCHITECTURE>

Specifies the target architecture. This is a shorthand syntax for setting the Runtime Identifier
(RID), where the provided value is combined with the default RID. For example, on a win-x64 machine,
specifying --arch x86 sets the RID to win-x86. If you use this option, don’t use the -r|--runtime op‐
tion. Available since .NET 6 Preview 7.

• -c|--configuration <CONFIGURATION>

Defines the build configuration. The default for most projects is Debug, but you can override the
build configuration settings in your project.

• --disable-build-servers

Forces the command to ignore any persistent build servers. This option provides a consistent way to
disable all use of build caching, which forces a build from scratch. A build that doesn’t rely on
caches is useful when the caches might be corrupted or incorrect for some reason. Available since .NET
7 SDK.

• -f|--framework <FRAMEWORK>

Publishes the application for the specified target framework. You must specify the target framework in
the project file.

• --force

Forces all dependencies to be resolved even if the last restore was successful. Specifying this flag
is the same as deleting the project.assets.json file.

• -?|-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.
Available since .NET Core 3.0 SDK.

• --manifest <PATH_TO_MANIFEST_FILE>

Specifies one or several target manifests to use to trim the set of packages published with the app.
The manifest file is part of the output of the dotnet store command. To specify multiple manifests,
add a --manifest option for each manifest.

• --no-build

Doesn’t build the project before publishing. It also implicitly sets the --no-restore flag.

• --no-dependencies

Ignores project-to-project references and only restores the root project.

• --nologo

Doesn’t display the startup banner or the copyright message.

• --no-restore

Doesn’t execute an implicit restore when running the command.

• -o|--output <OUTPUT_DIRECTORY>

Specifies the path for the output directory.

If not specified, it defaults to [project_file_folder]/bin/[configuration]/[framework]/publish/ for a
framework-dependent executable and cross-platform binaries. It defaults to [project_file_fold‐
er]/bin/[configuration]/[framework]/[runtime]/publish/ for a self-contained executable.

In a web project, if the output folder is in the project folder, successive dotnet publish commands re‐
sult in nested output folders. For example, if the project folder is myproject, and the publish output
folder is myproject/publish, and you run dotnet publish twice, the second run puts content files such
as .config and .json files in myproject/publish/publish. To avoid nesting publish folders, specify a
publish folder that isn’t directly under the project folder, or exclude the publish folder from the
project. To exclude a publish folder named publishoutput, add the following element to a PropertyGroup
element in the .csproj file:

<DefaultItemExcludes>$(DefaultItemExcludes);publishoutput**</DefaultItemExcludes>

• .NET 7.0.200 SDK and later

If you specify the --output option when running this command on a solution, the CLI will emit a warn‐
ing (an error in 7.0.200) due to the unclear semantics of the output path. The --output option is
disallowed because all outputs of all built projects would be copied into the specified directory,
which isn’t compatible with multi-targeted projects, as well as projects that have different versions
of direct and transitive dependencies. For more information, see Solution-level --output option no
longer valid for build-related commands.

• .NET Core 3.x SDK and later

If you specify a relative path when publishing a project, the generated output directory is relative
to the current working directory, not to the project file location.

If you specify a relative path when publishing a solution, all output for all projects goes into the
specified folder relative to the current working directory. To make publish output go to separate
folders for each project, specify a relative path by using the msbuild PublishDir property instead of
the --output option. For example, dotnet publish -p:PublishDir=.\publish sends publish output for
each project to a publish folder under the folder that contains the project file.

• .NET Core 2.x SDK

If you specify a relative path when publishing a project, the generated output directory is relative
to the project file location, not to the current working directory.

If you specify a relative path when publishing a solution, each project’s output goes into a separate
folder relative to the project file location. If you specify an absolute path when publishing a so‐
lution, all publish output for all projects goes into the specified folder.

• --os <OS>

Specifies the target operating system (OS). This is a shorthand syntax for setting the Runtime Identi‐
fier (RID), where the provided value is combined with the default RID. For example, on a win-x64 ma‐
chine, specifying --os linux sets the RID to linux-x64. If you use this option, don’t use the
-r|--runtime option. Available since .NET 6.

• --sc|--self-contained [true|false]

Publishes the .NET runtime with your application so the runtime doesn’t need to be installed on the
target machine. Default is true if a runtime identifier is specified and the project is an executable
project (not a library project). For more information, see .NET application publishing and Publish
.NET apps with the .NET CLI.

If this option is used without specifying true or false, the default is true. In that case, don’t put
the solution or project argument immediately after --self-contained, because true or false is expected
in that position.

• --no-self-contained

Equivalent to --self-contained false.

• --source <SOURCE>

The URI of the NuGet package source to use during the restore operation.

• -r|--runtime <RUNTIME_IDENTIFIER>

Publishes the application for a given runtime. For a list of Runtime Identifiers (RIDs), see the RID
catalog. For more information, see .NET application publishing and Publish .NET apps with the .NET
CLI. If you use this option, use --self-contained or --no-self-contained also.

• -v|--verbosity <LEVEL>

Sets the verbosity level of the command. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed],
and diag[nostic]. The default is minimal. For more information, see <xref:Microsoft.Build.Frame‐
work.LoggerVerbosity>.

• --use-current-runtime, --ucr [true|false]

Sets the RuntimeIdentifier to a platform portable RuntimeIdentifier based on the one of your machine.
This happens implicitly with properties that require a RuntimeIdentifier, such as SelfContained, Pub‐
lishAot, PublishSelfContained, PublishSingleFile, and PublishReadyToRun. If the property is set to
false, that implicit resolution will no longer occur.

• --version-suffix <VERSION_SUFFIX>

Defines the version suffix to replace the asterisk (*) in the version field of the project file.

EXAMPLES

       • Create a framework-dependent cross-platform binary for the project in the current directory:

                dotnet publish

         Starting  with  .NET  Core  3.0 SDK, this example also creates a framework-dependent executable for the
         current platform.

       • Create a self-contained executable for the project in the current directory, for a specific runtime:

                dotnet publish --runtime osx.10.11-x64

         The RID must be in the project file.

       • Create a framework-dependent executable for the project in the current directory, for a specific  plat‐
         form:

                dotnet publish --runtime osx.10.11-x64 --self-contained false

         The RID must be in the project file.  This example applies to .NET Core 3.0 SDK and later versions.

       • Publish the project in the current directory, for a specific runtime and target framework:

                dotnet publish --framework netcoreapp3.1 --runtime osx.10.11-x64

       • Publish the specified project file:

                dotnet publish ~/projects/app1/app1.csproj

       • Publish  the  current  application but don’t restore project-to-project (P2P) references, just the root
         project during the restore operation:

                dotnet publish --no-dependencies