Skip to main content
This guide will walk you through installing .NET Aspire on your machine, including all prerequisites and optional tools.

​
Prerequisites

.NET Aspire requires the following software to be installed on your system:

​
.NET SDK

1

Install .NET 9.0 or Later

Aspire requires .NET 9.0 SDK or later.Download and install from dotnet.microsoft.com/download
2

Verify Installation

Check your .NET version:
dotnet --version
You should see version 9.0.0 or higher.
If you have an older version of .NET, you can install multiple versions side-by-side. The Aspire CLI will use the correct version automatically.

​
Container Runtime

Aspire uses containers to run infrastructure services like databases, caches, and message queues during development.
Docker Desktop is the recommended choice for most users.Windows
  1. Download from docs.docker.com/desktop/install/windows-install
  2. Run the installer
  3. Restart your computer if prompted
  4. Start Docker Desktop from the Start menu
macOS
  1. Download from docs.docker.com/desktop/install/mac-install
  2. Drag Docker.app to your Applications folder
  3. Launch Docker from Applications
Linux
  1. Follow the installation guide at docs.docker.com/desktop/install/linux-install
  2. Start Docker Desktop
Verify Installation
docker --version
docker ps
Make sure your container runtime is running before you start an Aspire application. If it’s not running, you’ll get errors when Aspire tries to start containers.

​
Install Aspire CLI

The Aspire CLI is the primary tool for creating, running, and managing Aspire applications. Install the latest stable version of the Aspire CLI: 
irm https://aspire.dev/install.ps1 | iex

​
Daily Builds (Preview Features)

If you want to try the latest features before they’re released, you can install daily builds: 
iex "& { $(irm https://aspire.dev/install.ps1) } -Quality dev"
Daily builds are not supported for production use. They may contain bugs or breaking changes.

​
Verify Installation

Check that the CLI is installed correctly: 
aspire --version
You should see the version number, such as: 
9.4.1
The Aspire CLI is installed to ~/.aspire/bin on macOS/Linux or %USERPROFILE%\.aspire\bin on Windows. The installer automatically adds this to your PATH.If the aspire command isn’t found, restart your terminal or add the directory to your PATH manually.

​
Optional: Install VS Code Extension

The Aspire VS Code extension provides a better development experience with IntelliSense, debugging support, and integrated terminal commands.

​
Install Extension with CLI

The easiest way is to install both the CLI and extension together: 
iex "& { $(irm https://aspire.dev/install.ps1) } -InstallExtension"

​
Install Extension from VS Code

Alternatively, install directly from VS Code:
  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X)
  3. Search for “Aspire”
  4. Click Install on the .NET Aspire extension
If you use VS Code Insiders, add the -UseInsiders (PowerShell) or --use-insiders (bash) flag when installing with the CLI.

​
Optional: Configure Visual Studio

If you use Visual Studio, ensure you have the right version and workloads.

​
Requirements

  • Visual Studio 2022 version 17.14 or later
  • ASP.NET and web development workload

​
Install Visual Studio

1

Download Visual Studio

Get Visual Studio 2022 from visualstudio.microsoft.com/vs
2

Select Workloads

During installation, select:
  • ✅ ASP.NET and web development
  • ✅ .NET desktop development (optional, for desktop apps)
3

Launch and Verify

After installation, create a new Aspire project:
  1. File → New → Project
  2. Search for “Aspire”
  3. Select .NET Aspire Starter Application
  4. Click Create
Visual Studio has built-in support for Aspire. You don’t need to install a separate extension.

​
Platform-Specific Notes

​
Windows

  • PowerShell Execution Policy: If you get an error about execution policy when running the install script, run: 
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  • WSL2: If you’re using WSL2, you can install Aspire inside WSL and use Docker Desktop for Windows with WSL2 integration enabled.

​
macOS

  • Apple Silicon (M1/M2/M3): The Aspire CLI works natively on Apple Silicon. Make sure you have the ARM64 version of .NET installed.
  • Rosetta: You don’t need Rosetta for Aspire itself, but some container images may require it.

​
Linux

  • Alpine Linux: Aspire supports Alpine Linux, but requires additional setup for gRPC tooling. See the Alpine Linux section below.
  • Architecture: Aspire primarily supports x64/amd64. ARM64 support varies by integration.

​
Alpine Linux Setup

If you’re building on Alpine Linux, you need musl-compatible gRPC tooling:
  1. Install the gRPC plugins: 
    apk add --no-cache grpc-plugins
  2. Set environment variables to use the musl-compatible binaries: 
    export PROTOBUF_PROTOC=/usr/bin/protoc
export GRPC_PROTOC_PLUGIN=/usr/bin/grpc_csharp_plugin
  3. Add these to your shell profile (e.g., ~/.bashrc or ~/.zshrc) to make them permanent.
Alpine Linux support is not part of the official CI test suite. For production workloads, consider using a Debian-based distribution.

​
Verify Complete Installation

Let’s verify everything is installed correctly by creating a test project:
1

Create a Test Project

aspire new
When prompted:
  • Project name: test-app
  • Output path: ./test-app
  • Template version: stable
2

Navigate to Project

cd test-app
3

Run the Application

aspire run
You should see:
  • Build output
  • Dashboard URL
  • Resources starting up
  • Your browser opening to the dashboard
4

Verify Dashboard

In the dashboard, you should see:
  • 3 resources: cache, apiservice, webfrontend
  • All resources showing as “Running”
  • Green status indicators
5

Clean Up

Stop the app (Ctrl+C in terminal) and optionally delete the test project:
cd ..
rm -rf test-app
If all steps completed successfully, your installation is complete! You’re ready to start building Aspire applications.

​
Update Aspire

​
Update CLI

To update to the latest version of the Aspire CLI, run the installation command again: 
irm https://aspire.dev/install.ps1 | iex
The installer will detect the existing installation and update it.

​
Update Existing Projects

To update an existing project to use the latest Aspire packages: 
aspire update
This command:
  1. Updates all Aspire NuGet packages to the latest version
  2. Updates the NuGet.config if needed
  3. Restores packages
Run aspire update from the root directory of your Aspire solution.

​
Uninstall Aspire

If you need to uninstall Aspire:

​
Uninstall CLI

Delete the Aspire directory and remove from PATH:
Remove-Item -Recurse -Force "$env:USERPROFILE\.aspire"
Then remove %USERPROFILE%\.aspire\bin from your PATH environment variable.

​
Uninstall VS Code Extension

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X)
  3. Find the .NET Aspire extension
  4. Click Uninstall

​
Troubleshooting

The CLI installation directory is not in your PATH.On Windows, add to PATH:
  1. Open System Properties → Environment Variables
  2. Under User Variables, edit PATH
  3. Add %USERPROFILE%\.aspire\bin
  4. Restart your terminal
On macOS/Linux, add to your shell profile:
echo 'export PATH="$HOME/.aspire/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
When you run aspire run, you get an error about Docker not being available.Solution:
  1. Start Docker Desktop (Windows/Mac) or the Docker service (Linux)
  2. Wait for it to finish starting (you’ll see the icon in the system tray)
  3. Verify with docker ps
  4. Run aspire run again
You get a permission error when running Docker commands.Solution: Add your user to the docker group:
sudo usermod -aG docker $USER
newgrp docker
Or use Podman, which doesn’t require root privileges.
The dashboard or services can’t start because ports are already in use.Solution: Aspire will automatically try different ports. If you need to free up ports:Find what’s using a port:
# On Windows
netstat -ano | findstr :18888

# On macOS/Linux
lsof -i :18888
Kill the process or specify different ports in your AppHost:
builder.AddProject<Projects.Web>("web")
    .WithHttpEndpoint(port: 8080);
Package restore fails with errors about missing feeds or authentication.Solution:
  1. Make sure you have internet connectivity
  2. Clear NuGet caches: 
    dotnet nuget locals all --clear
  3. Try restoring again: 
    dotnet restore
When creating a new project in Visual Studio, Aspire templates don’t appear.Solution:
  1. Make sure you have Visual Studio 2022 17.14 or later
  2. Update to the latest version via Help → Check for Updates
  3. Repair Visual Studio installation if needed
  4. Restart Visual Studio

​
Next Steps

Now that Aspire is installed, you’re ready to build your first application!

Quickstart

Create and run your first Aspire app in 5 minutes

Core Concepts

Learn about the app model and how Aspire works

CLI Reference

Explore all CLI commands and options

Integrations

Discover available integrations for databases, messaging, and more

​
Additional Resources

If you encounter any issues not covered here, check the GitHub Issues or ask in the community Discord.

Build docs developers (and LLMs) love

Get started for freeTalk to us