Public | Automated Build

Last pushed: 6 days ago
Short Description
Official images for .NET Core for Linux and Windows Server 2016 Nano Server
Full Description

Supported tags and respective Dockerfile links

Note: The latest tag no longer uses the project.json project format, but has now been updated to be csproj/MSBuild-based. If you do not wish to migrate your existing projects to MSBuild simply change your Dockerfile to use the 1.1.0-sdk-projectjson or 1.1.0-sdk-projectjson-nanoserver tag. Going forward, new .NET Core sdk images will be MSBuild-based.

For more information about these images and their history, please see the relevant Dockerfile (dotnet/dotnet-docker). These images are updated via pull requests to the dotnet/dotnet-docker GitHub repo.

What is .NET Core?

.NET Core is a general purpose development platform maintained by Microsoft and the .NET community on GitHub. It is cross-platform, supporting Windows, macOS and Linux, and can be used in device, cloud, and embedded/IoT scenarios.

.NET has several capabilities that make development easier, including automatic memory management, (runtime) generic types, reflection, asynchrony, concurrency, and native interop. Millions of developers take advantage of these capabilities to efficiently build high-quality applications.

You can use C# to write .NET Core apps. C# is simple, powerful, type-safe, and object-oriented while retaining the expressiveness and elegance of C-style languages. Anyone familiar with C and similar languages will find it straightforward to write in C#.

.NET Core is open source (MIT and Apache 2 licenses) and was contributed to the .NET Foundation by Microsoft in 2014. It can be freely adopted by individuals and companies, including for personal, academic or commercial purposes. Multiple companies use .NET Core as part of apps, tools, new platforms and hosting services.

How to use these Images

Run a simple application within a container

You can run a sample application (Linux image) that depends on these images in a container by running the following command.

docker run microsoft/dotnet-samples

Run a .NET Core application with the .NET Core Runtime image

For production scenarios, you will want to deploy and run a pre-built application with a .NET Core Runtime image. This results in smaller Docker images compared to the SDK image. The SDK is not needed for production scenarios. You can try the instructions below or use the dotnetapp-prod sample if you want to try a pre-made version that's ready go.

You need to create a Dockerfile. Start by taking a dependency on a .NET Core runtime image by adding a FROM line to your Dockerfile:

FROM microsoft/dotnet:runtime

For Windows Containers, you should instead include the following line in your Dockerfile:

FROM microsoft/dotnet:nanoserver-runtime

Add the following additional lines to your Dockerfile.

WORKDIR /dotnetapp
COPY out .
ENTRYPOINT ["dotnet", "dotnetapp.dll"]

Build your application with the dotnet tools using the following commands:

dotnet restore
dotnet publish -c Release -o out

Build and run the Docker image:

docker build -t dotnetapp .
docker run -it --rm dotnetapp

The Dockerfile and the Docker commands assumes that your application is called dotnetapp. You can change the Dockerfile and the commands, as needed.

Build and run an application with a .NET Core SDK Image

You can use the .NET Core SDK Docker image as a build and runtime environment. It's a useful image for iterative development and the easiest way to get started using .NET Core with Docker. It isn't recommended for production since it's a bigger image than necessary, although it can work for that, too. You can try the instructions below or use the dotnetapp-dev sample if you want to try a pre-made version that's ready go.

In your Dockerfile, include the following line to reference the .NET Core SDK:

FROM microsoft/dotnet

For Windows Containers, you should instead include the Nanoserver version of the .NET Core SDK image:

FROM microsoft/dotnet:nanoserver

Add the following additional lines to your Dockerfile, which will both build and run your application in the container. This Dockerfile has been optimized (note the two COPY commands) to take advantage of Docker layering, resulting in faster image building for iterative development.

WORKDIR /dotnetapp

# copy project.json and restore as distinct layers
COPY project.json .
RUN dotnet restore

# copy and build everything else
COPY . .
RUN dotnet publish -c Release -o out
ENTRYPOINT ["dotnet", "out/dotnetapp.dll"]

You can then build and run the Docker image:

docker build -t dotnetapp .
docker run -it --rm dotnetapp

The Dockerfile and the Docker commands assumes that your application is called dotnetapp. You can change the Dockerfile and the commands, as needed.

Interactively build and run a simple .NET Core application

You can interactively try out .NET Core by taking advantage of the convenience of a container. Try the following set of commands to create and run a .NET Core application in a minute (depending on your internet speed).

docker run -it --rm microsoft/dotnet
[now in the container]
mkdir app
cd app
dotnet new console
dotnet restore
dotnet run
dotnet bin/Debug/netcoreapp1.0/app.dll
dotnet publish -c Release -o out
dotnet out/app.dll

The experience is very similar using Windows Containers. The commands should be the same, with the exception of the docker run (specifically the image name), ls and the directory separators. Try the following docker run command, to replace the docker run command above:

docker run -it --rm microsoft/dotnet:nanoserver

The steps above are intended to show the basic functions of .NET Core tools. Try running dotnet run twice. You'll see that the second invocation skips compilation. The subsequent command after dotnet run demonstrates that you can run an application directly out of the bin folder, without the additional build logic that dotnet run adds. The last two commands demonstrate the publishing scenario, which prepares an app to be deployed on the same or other machine, with a requirement on only the .NET Core Runtime, not the larger SDK. Naturally, you don't have to exit immediately, but can continue to try out the product as long as you want.

You can extend your interactive exploration of .NET Core by git cloning the dotnet/dotnet-docker-samples repo. Try the following commands (only works on Linux containers), assuming you are running interactively in the container:

git clone
cd dotnet-docker-samples
cd dotnetapp-dev
dotnet restore
dotnet run

Interactively build and run an ASP.NET Core application

You can interactively try out ASP.NET Core by taking advantage of the convenience of a container. Try the following set of commands to create and run an ASP.NET Core application in a minute (depending on your internet speed).

docker run -p 8000:80 -e "ASPNETCORE_URLS=http://+:80" -it --rm microsoft/dotnet
[now in the container]
mkdir app
cd app
dotnet new mvc
dotnet restore
dotnet run

After running dotnet run in the container, browse to http://localhost:8000 in your host machine.

The experience is very similar using Windows Containers. The commands should be the same, with the exception of the docker run (specifically the image name). Replace the docker run command above with the following two commands:

docker run -e "ASPNETCORE_URLS=http://+:80" -it --rm microsoft/dotnet:nanoserver

Copy the IP address from the output of ipconfig. After running dotnet run in the container, browse to that IP address in your browser on your host machine.

You should see a default ASP.NET Core site and logging activity in the container.

Please use the images at microsoft/aspnetcore. They are recommended and optimized for ASP.NET core development and production and are built on the images in this repo.

Image variants

The microsoft/dotnet images come in different flavors, each designed for a specific use case.


This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.

It contains the .NET Core SDK which is comprised of two parts:

  1. .NET Core
  2. .NET Core command line tools

Use this image for your development process (developing, building and testing applications).

There currently are two flavors of the sdk images, projectjson and msbuild. These two flavors exist while the transition occurs from project.json to msbuild. Once the tooling stabilizes, the project json variant will be deprecated and there will only be an msbuild variant.


This image contains the .NET Core (runtime and libraries) and is optimized for running .NET Core apps in production.


This image contains the operating system with all of the native dependencies needed by .NET Core. This is for self-contained applications.


There are multiple images for Windows Nanoserver, for .NET Core and Runtime distributions.

For more information on Windows Containers and a getting started guide, please see: Windows Containers Documentation.

More Examples using these Images

You can learn more about using .NET Core with Docker with .NET Docker samples:

  • Development sample using the sdk .NET Core SDK image.
  • Production sample using the runtime .NET Core image.
  • Self-contained sample using the runtime-deps base OS image (with native dependencies added).
  • Preview sample using a Preview sdk .NET Core SDK image.

Windows Container Dockerfile variants are provided at the same locations, above, and rely on slightly different .NET Core Docker images.

You can directly run a .NET Core Docker image from the microsoft/dotnet-samples repo.

See Building Docker Images for .NET Core Applications to learn more about the various Docker images and when to use each for them.

Related Repos

See the following related repos for other application types:


View license information for the software contained in this image.

.NET Core source code is separately licensed as MIT LICENSE.

The .NET Core Windows container images use the same license as the Windows Server 2016 Nano Server base image, as follows:



Microsoft Corporation (or based on where you live, one of its affiliates) (referenced as “us,” “we,” or “Microsoft”) licenses this Container OS Image supplement to you (“Supplement”). You are licensed to use this Supplement in conjunction with the underlying host operating system software (“Host Software”) solely to assist running the containers feature in the Host Software. The Host Software license terms apply to your use of the Supplement. You may not use it if you do not have a license for the Host Software. You may use this Supplement with each validly licensed copy of the Host Software.

Supported Docker versions

This image is officially supported on Docker version 1.12.2.

Please see the Docker installation documentation for details on how to upgrade your Docker daemon.

User Feedback


If you have any problems with or questions about this image, please contact us through a GitHub issue.


You are invited to contribute new features, fixes, or updates, large or small; we are always thrilled to receive pull requests, and do our best to process them as fast as we can.

Before you start to code, please read the .NET Core contribution guidelines.


You can read documentation for .NET Core, including Docker usage in the .NET Core docs. The docs are open source on GitHub. Contributions are welcome!

Docker Pull Command
Source Repository

Comments (20)
18 days ago

Community Announcement:
latest and nanoserver tags have been updated to refer to msbuild variants of the SDK. See an explanation in the RC4 release blog post.

4 months ago

@thinktainer latest still points to 1.0, as you noticed. That's intentional.

Quick version:

  • latest points to a stable release. 1.0 is stable. 1.1 is preview.
  • latest points to an LTS release. 1.1 is LTS. 1.1 is Current.

This is all covered in our latest blog post: Search on "latest" and "LTS".

4 months ago

It appears like the latest tag for the sdk image is out of sync with reality. From my understanding 1.0.0-preview2.1-sdk would be the latest?

4 months ago


You can simply apt-get install LLDB within your Dockerfile or create a layer you maintain between the .NET Core images and your app image.

5 months ago

Hi Team,

How can I get an image that which both contains the dotnet Core sdk and LLDB 3.8 be installed in the one same docker image?
Is there has any plans with it?

thanks a lot,
Kevin Yang

6 months ago

@3107, You will need to use the Windows Server Core or Nano Server specific images (e.g. microsoft/dotnet:windowsservercore or microsoft/dotnet:nanoserver). The microsoft/dotnet:latest image is a Debian based image. Windows Containers does not support running anything besides Windows based images.

Thanks Michael
Microsoft .NET Core Docker Team

6 months ago

Hi Team,

I am trying to pull the Microsoft/dotnet image by using docker pull Microsoft/dotnet on my WINDOWS 2016 TP5 machine. I can able to pull successfully Microsoft/iis, Microsoft/dotnet35, Microsoft/mssql-server-2014-express-windows. BUT NOT Microsoft/dotnet.

I am attaching error for your information. Please check and do the needful.

PS C:\Windows\system32> docker pull microsoft/dotnet
Using default tag: latest
latest: Pulling from microsoft/dotnet
357ea8c3d80b: Pulling fs layer
52befadefd24: Pulling fs layer
3c0732d5313c: Pulling fs layer
182cb80041a7: Pulling fs layer
a49b25f72e2d: Pulling fs layer
46be245fa43f: Pulling fs layer
a49b25f72e2d: Waiting
182cb80041a7: Waiting
46be245fa43f: Waiting
3c0732d5313c: Verifying Checksum
3c0732d5313c: Download complete
52befadefd24: Verifying Checksum
52befadefd24: Download complete
182cb80041a7: Verifying Checksum
182cb80041a7: Download complete
a49b25f72e2d: Verifying Checksum
a49b25f72e2d: Download complete
357ea8c3d80b: Verifying Checksum
357ea8c3d80b: Download complete
46be245fa43f: Verifying Checksum
46be245fa43f: Download complete
docker : failed to register layer: re-exec error: exit status 1: output: open
\?\C:\ProgramData\docker\windowsfilter\2c438123e197f226eaf7da709eaffcfa19705d5dfbaca9321f0bb9d10dada322\usr\share\man\man3\Locale::gettext.3pm.gz: The
filename, directory name, or volume label syntax is incorrect.
At line:1 char:1

  • docker pull microsoft/dotnet
  • ~~~~~~~~
    • CategoryInfo : NotSpecified: (failed to regis...x is incorrect.:String) [], RemoteException
    • FullyQualifiedErrorId : NativeCommandError

I am attaching my docker information for your reference. Requesting, Please go through the same and do the needful.

MY docker information
PS C:\Windows\system32> docker info
Containers: 1
Running: 0
Paused: 0
Stopped: 1
Images: 10
Server Version: 1.12.0
Storage Driver: windowsfilter
Logging Driver: json-file
Volume: local
Network: nat null overlay
Swarm: inactive
Security Options:
Kernel Version: 10.0 14300 (14300.1045.amd64fre.rs1_release_svc.160705-1059)
Operating System: Windows Server 2016 Standard Technical Preview 5
OSType: windows
Architecture: x86_64
CPUs: 4
Total Memory: 7.893 GiB
Docker Root Dir: C:\ProgramData\docker
Debug Mode (client): false
Debug Mode (server): false
Insecure Registries:


PS C:\Windows\system32> docker version
Version: 1.12.0
API version: 1.24
Go version: go1.6.3
Git commit: 8eab29e
Built: Thu Jul 28 23:54:00 2016
OS/Arch: windows/amd64

Version: 1.12.0
API version: 1.24
Go version: go1.6.3
Git commit: 8eab29e
Built: Thu Jul 28 23:54:00 2016
OS/Arch: windows/amd64


PS C:\Windows\system32> docker images

<none> <none> c7e73e171b5c 43 hours ago 8.918 GB
microsoft/mssql-server-2014-express-windows latest 5488a4ca54e0 8 days ago 10.15 GB
microsoft/dotnet35 latest 19f2f5823388 2 weeks ago 8.599 GB
microsoft/iis latest accd044753c1 2 weeks ago 7.907 GB
microsoft/windowsservercore latest 02cb7f65d61b 9 weeks ago 7.764 GB

7 months ago

@arnowu, Please open an issue for your question ( with the steps to reproduce what you have tried and the expected/actual outcome.

Thanks Michael
Microsoft .NET Core Docker Team

7 months ago

Why local area network of the computer can not access the host machine start service address? Firewall ports were opened. Port mapping is done when it is started

7 months ago

@jericpauldeleon, I tried my own repro steps and was able to get this to work. If you wouldn't mind you could open an issue at with the detailed steps to reproduce the problem and we can try to help you work through the issue.

Thanks Michael
Microsoft .NET Core Docker Team