Click here to Skip to main content
15,846,727 members
Articles / All Topics

Creating a Nuget Package - Step by Step

Rate me:
Please Sign up or sign in to vote.
5.00/5 (4 votes)
8 Nov 2017CPOL5 min read 79.4K   19   4
How to create a Nuget Package - step by step

Creating a Nuget Package - Step by Step

Creating a Nuget Package is a relatively straightforward process, but can be a little daunting the first time. This tutorial takes you through the process step by step.

Microsoft has comprehensive documentation on Nuget, but we've simplified the process here to help.

Your Project

Ideally your Nuget package should be a .NET Framework Class Library. In our instance, we use a C# instance, and the package is, for all intents, a normal class library.

Any files that you want to include in your package, such as documentation or a file, should be included in the project.

Creating a standard .NET Framework Class Library

Creating a .nuspec File

The main component of a Nuget package is the .nuspec file. This is an XML file that represents your package, and contains all the information that requires to publish your package.

Whilst not essential, it makes life somewhat easier if you include the .nuspec file in the root of your project.

An empty .nuspec file is shown below. This is the basic structure that you can use to create your first package.

<?xml version="1.0"?>
<package  xmlns="">
      <dependency id="" />
    <file src="" target="" />

A Real Example - Our ErrLog.IO .Nuspec File

<?xml version="1.0"?>
<package  xmlns="">
    <title>ErrLog.IO Error and Exception Logging Tool</title>
    <authors>Matthew Proctor, Michael Sanders, Alastair Bateman</authors>
    <description>ErrLog.IO is an exception and error logging tool</description>
    <releaseNotes>Bug fixes and performance improvements </releaseNotes>
    <copyright>Copyright 2017 Kutamo Pty. Ltd.</copyright>
    <tags>exceptions web http error logging</tags>
      <dependency id="Newtonsoft.Json" version="10.0"  />
    <summary>ErrLog.IO is an exception and error logging tool.</summary>
    <file src="" target="" />

Required .nuspec Elements

Element Description or Details
id The case-insensitive package identifier, which must be unique across IDs may not contain spaces or characters that are not valid for a URL, and generally follow .NET namespace rules.
version The version of the package, following the major.minor.patch pattern. Ensure you update this value for each subsequent package deployment.
description A long description of the package for UI display - this should be a description of your package and what functionality it provides..
authors A comma-separated list of packages authors, matching the profile names on

Useful, but Optional, .nuspec Elements

Element Description or Details
title Simply the title of your package, typically used in UI displays as on and the Package Manager in Visual Studio. If not specified, the package ID is used.
projectUrl A URL for your package's home page, often shown in UI displays as well as
licenseUrl A URL for your package's license, if it has one.
iconUrl A URL for a 64x64 image with transparent background to use as the icon for the package in UI display. This must be a fully qualified URL. If you don't specify one, your package will have the default Nuget logo.
releaseNotes A brief description of the changes made in this release of your package.
copyright Copyright details for your package.

The .nuspec file has a lot of additional configuration options, which are documented here.

A Picture is Worth a Thousand Pull Requests

To help differentiate your package from the thousands of others in the library, it's a great idea to create your own logo.

Logos must be a 64x64 pixel image with a transparent background, and are included in the <iconUrl></iconUrl> element of the .nuspec file.

Nuget Package Logo

Including a README.MD File

A file is a great way of providing your users with instructions on how to use your package.

This will be displayed in Visual Studio after your package is installed, and is written using markdown.

You can check out our readme file here.

Building Your Package

Once you've created your .nuspec file, it's now time to build your package!

Nuget.Org provides an application nuget.exe that is used to bundle your library into a Nuget package. You should already have this installed if you are using Visual Studio, or you can download it from

Nuget.exe needs to run from within your project folder, so the simplest method is to drop into this from a command prompt or powershell window.

cd \your_project_folder\

Nuget.Exe Package Repository

If your library uses any packages, you'll need to tell Nuget where they are on your PC. This is done by running nuget.exe with the -Set repositoryPath parameter.

Your packages folder is typically in the root folder of your Solution, if you're using Visual Studio.

nuget.exe config -Set repositoryPath="\full-path-to-your-packages-folder\"

We can now create our package. In the example below, we are setting the build configuration to Release.

nuget.exe pack -IncludeReferencedProjects -properties Configuration=Release

Using these options, Nuget will create a .nupkg that includes any referenced packages and projects.

The package filename is automatically created, using the format [package id].[package version].nupkg

For example, a recent ErrLog.IO package filename is

Deploying Your Package to Nuget.Org

Once you have your .nupkg file ready, you can now deploy it to Nuget.Org.

At this point, we're assuming you have already created an account on Nuget.Org, and have created an API Key.

Uploading a Package Manually

You can simply upload your .nupkg file to nuget by visiting

Nuget will open your package, read the .nuspec file, and publish your package all in a single step.

Automating and Scripting Deployment

nuget.exe has the ability of uploading your package automatically - this means you can write a script to automatically build and deploy your package simply and without interaction.

In order to upload your package via nuget.exe, we first need to set the API key. You can create an API key from within your account on Nuget.Org.

nuget.exe config setApiKey aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Once you've set the API Key, you can now push your package to Nuget.Org using Nuget.Exe. That sounds strange, no matter how many times you say it.

nuget.exe push [your-package-filename].nupkg -Source

Handy Hint!

The push command also supports wildcards, so you can just push any .nupkg file you have in the folder automatically with a single command.

nuget.exe push *.nupkg -Source

How We Build & Deploy the ErrLog.IO Nuget Package

We use a simple batch file to automatically build and deploy our ErrLog.IO Nuget Package, which we're happy to share below (with a few items obfuscated).

REM Move to project folder
cd E:\ErrLog\ErrLogNuget\

REM Configure Nuget Settings
nuget config -Set repositoryPath="E:\ErrLog\packages"
nuget setApiKey aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

REM Create Nuget Package
nuget pack -IncludeReferencedProjects -properties Configuration=Release

REM Deploy to Nuget.Org
nuget push *.nupkg -Source

Nuget Statistics

Your Nuget package page gives you a handy summary of your package downloads, as well as more detail in the form of a pivot table, allowing you to review downloads per version and per client type.

Nuget Package Summary

Final Thoughts

Deploying a Nuget package for worldwide distribution is easy, but it's also easy to accidentally deploy a broken package, as testing is your responsibility.

Make sure you have a solid test process for downloading and validating your package as soon as it's published, to ensure that your users have a great, and bug-free, experience.



This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
CEO Kutamo and ErrLog.IO
Australia Australia
Pluralsight Author, .Net Developer, Writer & Blogger

I am an Australian IT professional based in Melbourne, Victoria, Australia.

I'm a polyglot programmer, being proficient in a number of languages and frameworks including C#, VB.Net, F#, Javascript, Perl, Powershell and Z80 & 6502 assembly. Smile | :)

Comments and Discussions

QuestionShort on Info Pin
#realJSOP10-Aug-19 4:33
mve#realJSOP10-Aug-19 4:33 
QuestionThank you very much for the article. Pin
Member 1264161820-May-18 22:29
Member 1264161820-May-18 22:29 
AnswerRe: Thank you very much for the article. Pin
#realJSOP10-Aug-19 4:28
mve#realJSOP10-Aug-19 4:28 
GeneralMy vote of 5 Pin
Franc Morales12-Apr-18 23:26
Franc Morales12-Apr-18 23:26 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.