How to Install ASP.NET Core: A Complete Step-by-Step Guide for Developers

Learning how to install ASP.NET Core is the essential first step for any developer who wants to build modern, cross-platform web applications using Microsoft's powerful open-source framework. ASP.NET Core runs on Windows, macOS, and Linux, making it one of the most versatile server-side frameworks available today. Whether you're setting up a local development environment or preparing a production server, the installation process is straightforward once you understand what each component does and why it matters for your workflow.

ASP.NET Core is part of the broader .NET ecosystem, which Microsoft completely reimagined starting with .NET Core 1.0 in 2016. Since then, the platform has evolved rapidly, with .NET 8 being the current Long-Term Support (LTS) release as of late 2023. Each new version brings performance improvements, new language features, and expanded platform support. Understanding which version to install — LTS versus Standard-Term Support (STS) — is one of the first decisions you'll make, and it has real implications for how long your chosen runtime will receive security patches and updates.

Before diving into the installation steps, it helps to understand the two main download options Microsoft offers: the SDK and the Runtime. The .NET SDK (Software Development Kit) includes everything you need to build and run .NET applications — compilers, libraries, tools like the dotnet CLI, and the runtime itself. The Runtime, on the other hand, is a smaller package designed purely for running already-compiled applications. If you're a developer writing code, you want the SDK. If you're configuring a server that only needs to host a finished application, the Runtime is sufficient and keeps your server footprint smaller.

For many developers, the most confusing part of getting started with ASP.NET Core is understanding how .NET versioning works alongside the older .NET Framework. The classic .NET Framework (versions 1.0 through 4.8) is Windows-only and ships with the operating system. ASP.NET Core, by contrast, is installed separately and runs side-by-side with other .NET versions on the same machine. You can have .NET 6, .NET 7, and .NET 8 all installed simultaneously without conflict, and each project can target whichever version it needs via a simple property in the project file.

The dotnet CLI is the command-line interface that serves as the backbone of .NET development. Once you install asp.net core via the SDK, the dotnet command becomes available in your terminal. With it, you can create new projects, add NuGet packages, run applications, execute tests, publish builds for deployment, and much more. Mastering even a handful of dotnet CLI commands dramatically speeds up your development workflow and reduces dependence on GUI-heavy IDEs for routine tasks.

This guide walks you through the complete installation process across all major operating systems, explains how to verify your installation, and covers common troubleshooting scenarios that developers encounter. By the end, you'll have a fully functional ASP.NET Core development environment and a clear mental model of how the different pieces — SDK, Runtime, CLI, and IDE tooling — fit together. You'll also learn how to configure environment variables, manage multiple SDK versions, and set up your first project to confirm everything is working correctly.

Whether you're completely new to .NET development or migrating from the classic ASP.NET Framework, this installation guide gives you the solid foundation you need. The process takes roughly 10 to 20 minutes on most systems, and the knowledge you build here will serve you throughout your entire ASP.NET Core career, from local development all the way through to production deployment on cloud platforms like Azure, AWS, and Google Cloud.

Once the installation finishes, verifying that everything works correctly is a critical step that many developers skip — only to spend frustrating hours debugging issues that could have been caught immediately. The primary verification command is dotnet --version, which prints the version of the highest-priority SDK installed on your machine. However, this single command only scratches the surface of what you should confirm before starting a real project. Running dotnet --info gives you a comprehensive readout including the SDK version, runtime environment details, OS information, and the paths where .NET is installed on your system.

The dotnet --list-sdks command is particularly valuable on developer machines where multiple .NET versions coexist. Each SDK appears on its own line with its version number and the directory where it's installed. Similarly, dotnet --list-runtimes shows every runtime installed, which matters because an SDK typically installs its matching runtime, but you may have additional runtimes for hosting older or newer apps. Understanding these lists helps you troubleshoot version conflicts and ensures your projects target the runtime version you intend.

A common issue developers encounter after installation is the PATH variable not being updated correctly, especially on Linux and macOS when installing via a compressed archive rather than a package manager. If dotnet returns a command-not-found error, you need to add the .NET installation directory to your PATH in your shell profile. For bash, add export PATH=$PATH:$HOME/.dotnet to your ~/.bashrc or ~/.bash_profile file. For zsh (the default on modern macOS), add the same line to ~/.zshrc. Always open a new terminal session or run source ~/.bashrc after making changes.

After confirming the CLI works, the next verification step is creating and running a minimal test application. The command dotnet new console -o TestApp && cd TestApp && dotnet run creates a Hello World console app and runs it immediately. While this doesn't specifically test ASP.NET Core web hosting, it confirms the SDK's core compilation and execution pipeline is functional. For a more thorough test, use dotnet new webapp -o WebTest && cd WebTest && dotnet run to spin up a Razor Pages app with the Kestrel web server — this validates the full ASP.NET Core stack.

HTTPS is enabled by default in ASP.NET Core development, which requires a trusted development certificate. After installation, run dotnet dev-certs https --trust to generate and trust a local development certificate. On Windows and macOS, this opens a dialog asking you to confirm trusting the certificate — click Yes. On Linux, certificate trust must be handled differently depending on your browser and distribution, as there is no system-wide trust store. Without this step, your browser will show security warnings every time you open a local ASP.NET Core app in development.

Environment variables also play an important role in ASP.NET Core's behavior. The ASPNETCORE_ENVIRONMENT variable controls which configuration settings are loaded and whether developer-friendly features like detailed error pages are enabled. Set it to Development on your local machine, Staging on pre-production servers, and Production on live servers. You can set this variable in your shell profile, in a launchSettings.json file inside the project's Properties folder, or through your IDE's run configuration. Forgetting to set this variable is a common source of confusing behavior for developers new to the framework.

Finally, confirm your IDE tooling is correctly picking up the installed SDK. In Visual Studio 2022, navigate to Help → About and check the .NET SDK version listed. In VS Code, open a .cs file and verify the C# Dev Kit extension shows no errors in the status bar. In JetBrains Rider, go to Settings → Build, Execution, Deployment → Toolset and SDK to see detected .NET installations. When the IDE and CLI agree on the SDK version, you can be confident your development environment is consistent and ready for real project work.

Managing multiple .NET SDK versions on a single machine is a reality for most professional developers, especially those maintaining multiple projects that target different framework versions. Unlike Node.js, which requires tools like nvm to switch versions, the .NET SDK has version management built directly into the platform. The dotnet CLI automatically selects the appropriate SDK version based on the nearest global.json file in the directory hierarchy, walking up from the current working directory until it finds one or falls back to the latest installed SDK.

The global.json file is a small JSON file that specifies the required SDK version and an optional rollForward policy. The rollForward policy controls what happens when the exact specified version isn't installed. A value of latestMinor allows the CLI to use a newer minor version, while disable causes it to fail with an error if the exact version isn't present — useful for guaranteeing reproducible builds. Understanding rollForward policies is especially important in CI/CD environments where SDK versions may differ from developer machines.

When you install a new SDK version, it doesn't replace the old one — both coexist in the installation directory. On Windows, all SDKs live under C:\Program Files\dotnet\sdk\. On macOS and Linux via package manager, they typically live under /usr/share/dotnet/sdk/. You can have .NET 6, .NET 7, and .NET 8 SDKs installed simultaneously, and each project will use whichever version its global.json specifies or the latest available SDK if no global.json is present.

Removing old SDK versions is occasionally necessary to reclaim disk space or clean up development machines. On Windows, use the .NET Uninstall Tool (a free Microsoft utility) to safely remove specific SDK and runtime versions without accidentally breaking applications that depend on them. On macOS and Linux with a package manager, use the package manager's remove command for the specific version package. Be cautious: removing a runtime version that a deployed application depends on will break that application — always verify what's in use before uninstalling.

For teams with strict version requirements, Docker is increasingly the preferred solution for .NET version management. Microsoft publishes official .NET Docker images on the Docker Hub and the Microsoft Container Registry, covering every supported .NET version on multiple base images including Alpine (for minimal size), Ubuntu, and Debian. A Dockerfile that begins with FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build ensures that every developer, CI server, and production environment uses exactly the same SDK version, completely eliminating environment-specific installation issues.

The .NET SDK also ships with a built-in workload system for optional platform-specific capabilities. Workloads extend the SDK with support for platforms like .NET MAUI (cross-platform mobile and desktop), Blazor WebAssembly AOT compilation, and Android/iOS development. Run dotnet workload list to see installed workloads and dotnet workload install maui to add new ones. Unlike the core SDK, workloads can be updated independently and may require elevated permissions to install on some systems.

For developers who prefer a visual approach to SDK management, Visual Studio's Visual Studio Installer provides a graphical interface for adding and removing .NET workloads and SDK versions. Each Visual Studio installation can be configured independently, and the installer handles dependencies automatically. However, SDKs installed through Visual Studio are visible to the dotnet CLI system-wide, so there's no isolation between Visual Studio and CLI-based development on the same machine. Both always see all installed SDKs regardless of which installer was used to add them.

Creating your first ASP.NET Core project after installation is one of the most satisfying moments in a developer's journey with the platform. The dotnet CLI provides a rich set of project templates that scaffold complete working applications in seconds, giving you an immediately runnable starting point rather than a blank canvas. The dotnet new command is your entry point, and running dotnet new list displays every available template including web apps, API projects, Blazor apps, gRPC services, class libraries, test projects, and more.

For a standard web application with server-rendered pages, dotnet new webapp creates a Razor Pages project — the recommended starting point for content-focused web sites. For a REST API backend, dotnet new webapi creates an API project with a sample weather forecast controller and Swagger UI integration pre-configured. For a minimal API without controller classes, add the --use-minimal-apis flag. Each template creates a complete project with a properly configured Program.cs, an appsettings.json configuration file, and a launchSettings.json that defines the development server URLs.

Understanding the Program.cs file is essential for anyone learning ASP.NET Core. In .NET 6 and later, the traditional Startup.cs class was merged into a single Program.cs using C# top-level statements. This file has two logical sections: the service registration section where you call methods on builder.Services to register dependencies, and the middleware pipeline section where you call methods on app to configure the request processing pipeline. This two-phase pattern — register services, then build and configure the pipeline — is the heart of ASP.NET Core's architecture.

The appsettings.json file is ASP.NET Core's primary configuration mechanism. It's a JSON file that can contain database connection strings, API keys, feature flags, logging levels, and any other application settings. A companion file named appsettings.Development.json is loaded additionally in the Development environment and its values override the base file — this lets you keep production-safe defaults in the main file while using development-specific values locally. Never commit secrets like API keys to appsettings files in source control; use the Secret Manager tool (dotnet user-secrets) for local development secrets instead.

Running the application is as simple as executing dotnet run from the project directory. The CLI compiles the project, starts the Kestrel web server, and prints the URLs where the app is listening — typically http://localhost:5000 and https://localhost:5001. For hot reload during development, use dotnet watch run instead — this watches source files for changes and automatically recompiles and restarts (or in many cases applies changes without a full restart) whenever you save a file, dramatically speeding up the edit-compile-test cycle.

For production hosting, you'll want to explore your deployment options early. ASP.NET Core applications can be hosted behind IIS on Windows (using the Hosting Bundle and the ASP.NET Core Module), behind Nginx or Apache on Linux, directly as systemd services, or in Docker containers. Microsoft Azure App Service, AWS Elastic Beanstalk, and Google Cloud Run all support ASP.NET Core out of the box. The dotnet publish command prepares your application for deployment by compiling it in Release mode and copying all necessary files to an output folder that you then transfer to your hosting environment.

As you build your first application and explore the framework, investing time in understanding the middleware pipeline pays enormous dividends. Every HTTP request in ASP.NET Core flows through a series of middleware components in the order they are registered in Program.cs. Built-in middleware handles tasks like static file serving, HTTPS redirection, authentication, authorization, routing, and session management.

Custom middleware lets you intercept and modify requests and responses at any point in the pipeline. This composable, explicit pipeline architecture is one of the most elegant aspects of ASP.NET Core and a major reason for its performance advantage over older web frameworks that relied on more opaque request processing models.

Troubleshooting installation issues is an inevitable part of setting up any development environment, and ASP.NET Core has its fair share of gotchas that trip up even experienced developers. The most common issue after a fresh install is the dotnet command not being found in the terminal. This almost always means the installation directory wasn't added to the system PATH, either because the installer failed partway through or because you're using a shell that hasn't sourced its profile since the installation. Always open a brand-new terminal window after installation rather than reusing one that was open during the process.

Port conflicts are another frequent stumbling block. By default, dotnet run tries to use ports 5000 and 5001. If another process is already using those ports, the app fails to start with a binding exception. You can change the ports in launchSettings.json, pass a different URL via the --urls CLI argument (e.g., dotnet run --urls http://localhost:5050), or set the ASPNETCORE_URLS environment variable. On Linux and macOS, ports below 1024 require root privileges — always use ports above 1024 for local development to avoid permission errors.

Certificate trust problems are extremely common on Linux, where there's no unified system trust store that works across all browsers and tools. The dotnet dev-certs https --trust command works reliably on Windows and macOS, but on Linux it currently only trusts the certificate for .NET's own HTTPS connections — it does not automatically trust it in Firefox, Chrome, or other browsers. On Ubuntu, you can manually add the certificate to the system trust store using update-ca-certificates. Alternatively, configure your project to use HTTP only during development by modifying the applicationUrl in launchSettings.json to remove the HTTPS entry.

NuGet package restore failures are another category of installation-adjacent issues. When you first open or build a new project, the dotnet CLI fetches all required NuGet packages from the configured package source (nuget.org by default). In corporate environments behind a proxy or firewall, this can fail silently or with cryptic SSL errors. You may need to configure the HTTPS_PROXY environment variable, add your organization's package feed as a source in a NuGet.config file, or work with your network team to whitelist the NuGet CDN domains. The dotnet nuget list source command shows which feeds are currently configured.

SDK version mismatches between team members or between local development and CI/CD pipelines cause intermittent and hard-to-diagnose build failures. A project that builds perfectly locally with .NET SDK 8.0.300 may fail on a CI server running 8.0.100 if it uses features or compiler behaviors introduced in the newer patch version. The solution is always the global.json file with a specific version pinned. Add this file to source control so that every developer and every CI runner uses exactly the same SDK version, and update it deliberately rather than letting it drift as developers upgrade their local SDKs independently over time.

On macOS with Apple Silicon (M1, M2, M3 chips), verify that you're downloading the ARM64 version of the .NET SDK rather than the x64 version. While x64 binaries run through Rosetta 2 translation on Apple Silicon, the ARM64 SDK runs natively and delivers significantly better build performance and lower power consumption. The .NET download page automatically detects your architecture in most browsers, but double-check before downloading, particularly on CI systems where the wrong architecture can cause subtle performance and compatibility issues that are difficult to trace back to the SDK download.

Finally, for developers working in containerized environments with Docker Desktop on Windows using WSL2 (Windows Subsystem for Linux 2), be aware that SDKs installed in the Windows host environment are not automatically available inside WSL2 distributions. Each WSL2 distribution is effectively a separate Linux environment requiring its own .NET SDK installation. Use the Linux package manager instructions for your WSL2 distro, not the Windows installer. Once installed inside WSL2, the dotnet CLI works exactly as it would on a native Linux system, complete with full path and environment variable support within the WSL2 terminal session.