To start developing native, cross-platform .NET MAUI apps on Windows, install Visual Studio 2022 17.8 or greater by following the installation steps.
Prerequisites
- Visual Studio 2022 17.8 or greater. For information about supported operating systems, hardware, supported languages, and additional requirements and guidance, see Visual Studio 2022 System Requirements.
To build, sign, and deploy .NET MAUI apps for iOS, you'll also need:
Alternatively, to deploy debug builds of your app directly from Windows to your iOS device with hot restart, you'll need:
Installation
To create .NET MAUI apps, you'll need the latest version of Visual Studio 2022:
Either install Visual Studio, or modify your existing installation, and install the .NET Multi-platform App UI development workload with its default optional installation options:
Note
Visual Studio for Mac is scheduled for retirement by August 31 2024 in accordance with Microsoft's Modern Lifecycle Policy. Visual Studio for Mac 17.6 will continue to be supported until August 31 2024, with servicing updates for security issues and updated platforms from Apple. For more information, including alternative options for developing on a Mac, see What's happening to Visual Studio for Mac?.
To start developing native, cross-platform .NET MAUI apps on macOS, install Visual Studio 2022 for Mac 17.6 by following the installation steps.
Prerequisites
To build, sign, and deploy .NET MAUI apps for iOS or macOS, you'll also need:
Installation
To create .NET MAUI apps, you'll need the latest Visual Studio for Mac:
Either install Visual Studio 2022 for Mac, or modify your existing installation, and ensure that the following workloads are installed:
- .NET
- .NET MAUI
- Android
- iOS
Important
For new installations of Visual Studio 2022 for Mac, selecting the .NET MAUI workload will automatically select the Android and iOS workloads, which are currently required for .NET MAUI development.
Install .NET 8 through the standalone installer.
After .NET 8 has finished installing, run dotnet workload install maui in a terminal.
If you have network trouble while installing in a corporate environment, review the installing behind a firewall or proxy instructions.
Installation behind a firewall or proxy server
To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must be made accessible in order to allow downloads of the required tools and updates for your software. For more information about configuring your network to allow access to the required endpoints, see Install and use Visual Studio for Mac behind a firewall or proxy server.
Note
.NET MAUI support in Visual Studio Code is still in preview. Try it out and share your feedback!
Install Visual Studio Code and the .NET MAUI extension
Install Visual Studio Code.
In the Extensions tab, search for ".NET MAUI" and install the .NET MAUI extension. The .NET MAUI extension automatically installs the C# Dev Kit and C# extensions, which are required for the .NET MAUI extension to run.
Note
The .NET MAUI extension requires the C# Dev Kit and prerelease C# extensions. You must sign into C# Dev Kit to use the .NET MAUI extension's functionality. See this blog post for more information about C# Dev Kit and its family of extensions.
To develop with .NET MAUI in Visual Studio code, you need to have .NET, the .NET MAUI workload, and a valid target platform based on your development machine's operating system:
| Your Operating System |
Supported Target Platforms |
| Windows |
Windows, Android |
| macOS |
Android, iOS, macOS |
| Linux |
Android |
Windows
The recommended approach to setup your Windows machine for .NET MAUI development is through the Visual Studio installer. You can follow the instructions in the Visual Studio tab on this page to walk through installing the .NET MAUI workload. You can also use Visual Studio to manage different versions of Android, create emulators, update .NET and .NET MAUI, and more.
If you don't want to install Visual Studio, you can still get set up for .NET MAUI development by following these steps:
- Install .NET 8.
- After .NET has finished installing, run
dotnet workload install maui in a terminal.
- If you'd like to debug Android in Visual Studio Code, you also have to:
- Install Microsoft OpenJDK 11.
- Install the Android SDK. You can acquire the correct versions of the Android SDK and build tools by creating a new .NET MAUI project (
dotnet new maui) and running the following command in your terminal:
dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory="<ANDROID SDK DIRECTORY>" -p:AcceptAndroidSDKLicenses=True
On Windows, the suggested Android SDK directory value is %LOCALAPPDATA%/Android/Sdk.
macOS
- Install .NET 8.
- Install the latest stable Xcode.
- After Xcode has finished installing, run
xcode-select --install in a terminal to acquire the Xcode command line tools.
- Run
dotnet workload install maui in a terminal.
- If you'd like to debug to Android in Visual Studio Code, you also have to:
- Install Microsoft OpenJDK 11.
- Install the Android SDK. You can acquire the correct versions of the Android SDK and build tools by creating a new .NET MAUI project (
dotnet new maui) and running the following command in your terminal:
dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory="<ANDROID SDK DIRECTORY>" -p:AcceptAndroidSDKLicenses=True
On macOS, the suggested Android SDK directory value is $HOME/Library/Android/sdk.
Linux
- Install .NET 8.
- After .NET has installed, run
dotnet workload install maui-android in a terminal.
- If you'd like to debug to Android in Visual Studio Code, you also have to:
- Install Microsoft OpenJDK 11.
- Install the Android SDK from your preferred package manager, or from the Android website.
Troubleshooting
You might face issues when setting up the .NET MAUI extension for Visual Studio Code. If you're still facing issues after following the below troubleshooting steps, please report an issue.
Project creation
If you try to create a new project and the file explorer keeps popping up in an infinite loop, you may not be selecting an empty folder. Check that there are no hidden files or folders, create a new folder, or create your .NET MAUI app from the command line using dotnet new maui.
Android setup
There are multiple ways you can set up and manage Android SDKs on your machine:
No matter which way you install Android, you can develop .NET MAUI apps in Visual Studio Code. If the following troubleshooting steps don't solve your issue, please Report a Problem.
Using "InstallAndroidDependencies"
- .NET 8 has a build target that helps set up your Android environment for you. You can add or remove the following properties to
dotnet build -t:InstallAndroidDependencies -f:net8.0-android to configure your machine:
-p:AndroidSdkDirectory "<PATH>" installs or updates Android dependencies to the specified path (Note: You must use an absolute path without a tilde "~").-p:JavaSdkDirectory "<PATH>" installs Java to the specified path (Note: You must use an absolute path without a tilde "~").-p:AcceptAndroidSDKLicenses=True accepts the necessary Android licenses for development.
There's an error that the Android SDK or Java SDK was not found
- Open the command palette (Ctrl/Cmd + Shift + P) and search for the
.NET MAUI: Configure Android command. Select both "Set Android SDK path" and "Set Android JDK path" and validate that they point to installations of each.
- The Android SDK folder should have sub-folders such as
build-tools, cmdline-tools, and platform-tools.
- The Java OpenJDK folder should have sub-folders such as
bin, lib, and more.
- On Windows, if you install via Visual Studio, the Java SDK will be in
C:\Program Files\Microsoft\ and Android SDK will be in C:\Program Files (x86)\Android\android-sdk.
- Set the
JAVA_HOME environment variable to a valid Java OpenJDK path.
- Set the
ANDROID_HOME environment variable to your Android SDK path.
- Check your minimum versions of installed Android dependencies:
- build-tools >= 32.0.0
- cmdline-tools == 7.0
- platforms;android-33*
- .NET 7: platform-tools = 33.0.2
- .NET 8: platform-tools = 34.0.1
There's an error that Android licenses aren't accepted
In an elevated command prompt or terminal, navigate to your Android SDK's cmdline-tools/latest/bin/ folder and run sdkmanager --licenses then follow the CLI prompts.
My Android dependencies aren't loading in the Solution Explorer, but my app builds fine
This is a known issue if you install to %APPDATA% on Windows and will be fixed in a future release.
iOS/Xcode Setup
- If you get an error that Xcode is not found, run
xcode-select --install in a terminal, then check that xcode-select -p points to your Xcode installation.
- If you're still facing issues, open Xcode itself to make sure it loads correctly. Once Xcode is open, navigate to Xcode > Settings > Locations and check that the Command Line Tools field is pointing to the correct Xcode.
- There is a known issue that sometimes you have to build your iOS/macOS app twice for it to deploy. This will be fixed in an upcoming release.
Debugging issues
- Debugging can fail to start for multiple reasons. If there isn't a clear error in the Output window, first double check that you are using the ".NET MAUI" run configuration in Visual Studio Code.
- You can try a command line build from the terminal to see if the error is with your code or the .NET MAUI extension. For example, you could run
dotnet build -f:net8.0-android to see if your Android build succeeds outside of Visual Studio Code. If this build succeeds, please Report an Issue
Known Limitations
This extension is still in early preview, so there are a number of known limitations. Please give us your feedback on other features you'd like to see as we continue building this new experience.
- XAML editing capabilities are very lightweight - you get basic syntax highlighting and autocomplete. We're exploring how to improve the XAML experience in a future release.
- Currently, you can't switch the target framework for IntelliSense (it will show syntax highlighting for only the first target framework listed in your .csproj file). This capability is in progress.
- XAML and .NET Hot Reload are't currently supported.
- This extension hasn't yet been fully tested with the latest iOS and Xcode betas.
Please give us your feedback on other features you'd like to see as we continue building this new experience!
Provide Feedback
Please read the C# Dev Kit FAQs and check existing Known Issues before filing a new issue or suggestion. You can file suggestions and issues from inside Visual Studio Code through through the Help > Report Issue dialog. Ensure you select “An extension” then the .NET MAUI extension in the drop-down.
