Last Updated:

A Complete Guide to Downloading, Installing, and Using Microsoft Build of OpenJDK 17

The Microsoft Build of OpenJDK 17 is a free, open-source, long-term support (LTS) distribution of the Java Development Kit, backed by Microsoft and aligned 100% with upstream OpenJDK standards. Released in September 2021, it receives 8 years of free public support (until September 2029), with extended paid support available for enterprise customers.

As the default JDK for all Azure Java workloads, it is optimized for integration with the Microsoft ecosystem (VS Code, Azure Spring Apps, GitHub Actions, etc.) while remaining a fully TCK-compliant drop-in replacement for any other OpenJDK distribution. It supports x64 and ARM64 architectures across Windows, macOS, and Linux, including musl-based Alpine Linux for containerized workloads, with no commercial licensing fees for any use case.

This guide covers end-to-end steps to download, install, configure, and use Microsoft OpenJDK 17, along with best practices and troubleshooting tips for both individual developers and enterprise teams.

Table of Contents#

  1. Prerequisites for Installation
  2. Key Benefits of Choosing Microsoft OpenJDK 17
  3. Step-by-Step Download & Installation Guides 3.1 Windows 3.2 macOS 3.3 Linux
  4. Post-Installation Verification Steps
  5. Configuration Best Practices
  6. Example Usage: Building a Java 17 Application
  7. Troubleshooting Common Installation Issues
  8. Migrating to Microsoft OpenJDK 17 from Other Distributions
  9. References

Prerequisites for Installation#

Before you begin, ensure your system meets the following requirements:

RequirementDetails
Operating SystemWindows 10+/Server 2016+, macOS 11 (Big Sur)+, RHEL 7+, Ubuntu 18.04+, Debian 10+, Alpine 3.14+
Architecturex64, ARM64 (Apple Silicon, AWS Graviton, etc.)
Disk Space~300MB compressed installer, ~1GB uncompressed installation
PermissionsAdmin/root access for system-wide installation, no special permissions for per-user installs

Key Benefits of Choosing Microsoft OpenJDK 17#

  1. Guaranteed LTS Support: 8 years of free public security and performance updates, aligned with OpenJDK's quarterly Critical Patch Update (CPU) cadence.
  2. 100% TCK Compliant: Passes all Java SE 17 Technology Compatibility Kit tests, ensuring no compatibility gaps with standard Java specifications.
  3. Ecosystem Optimizations: Pre-integrated with VS Code Java tooling, Azure App Service, Azure Functions, and GitHub Actions Java runners for reduced configuration overhead.
  4. Container-First Design: Small, hardened container images available on Microsoft Container Registry (MCR), with built-in support for Class Data Sharing (CDS) and Kubernetes memory limit auto-detection.
  5. No Licensing Costs: Free for commercial and non-commercial use, with no subscription or usage fees, unlike Oracle's commercial JDK distributions.

Step-by-Step Download & Installation Guides#

You can install Microsoft OpenJDK 17 either via manual download or your operating system's native package manager (recommended for easier updates).

Windows#

Option 1: Manual Install (MSI)#

  1. Navigate to the official Microsoft OpenJDK download page
  2. Under the OpenJDK 17 section, select the Windows x64 or ARM64 MSI installer matching your system architecture
  3. Run the installer, and select the following optional (recommended) features during setup:
    • Add JAVA_HOME to system environment variables
    • Add the JDK bin directory to the system PATH
    • Associate .jar files with the Java runtime
  4. Complete the installation wizard

Option 2: Package Manager (Winget)#

For Windows 11 and newer Windows 10 builds with Winget pre-installed, run the following command in an elevated PowerShell window:

winget install Microsoft.OpenJDK.17

macOS#

Option 1: Manual Install (PKG)#

  1. Download the macOS x64 or ARM64 PKG installer from the official download page
  2. Open the PKG file and follow the setup prompts; the installer will automatically install the JDK to /Library/Java/JavaVirtualMachines/microsoft-17.jdk/

Option 2: Homebrew#

Run the following commands in a terminal:

# Add Microsoft's OpenJDK tap
brew tap microsoft/openjdk
# Install Microsoft OpenJDK 17
brew install --cask microsoft-openjdk@17

Note: For Apple Silicon (M1/M2/M3) devices, the ARM64 build runs natively with no Rosetta 2 emulation required.

Linux#

Debian/Ubuntu (APT)#

# Import Microsoft's GPG signing key
wget -O - https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
# Add the Microsoft product repository
echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/microsoft.list
# Update package lists and install
sudo apt update && sudo apt install msopenjdk-17

RHEL/CentOS/Fedora (DNF/YUM)#

# Import Microsoft's GPG signing key
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
# Add the Microsoft product repository
sudo wget -O /etc/yum.repos.d/microsoft-prod.repo https://packages.microsoft.com/config/rhel/$(rpm -E %rhel)/prod.repo
# Install the JDK
sudo dnf install msopenjdk-17

Alpine Linux#

# Add Microsoft's APK repository
echo "https://packages.microsoft.com/alpine/v$(cut -d'.' -f1,2 /etc/alpine-release)/main" | sudo tee -a /etc/apk/repositories
# Import Microsoft's GPG key
sudo wget -O /etc/apk/keys/[email protected] https://packages.microsoft.com/keys/microsoft.asc
# Install Microsoft OpenJDK 17
sudo apk add --no-cache microsoft-openjdk17

Manual Tar.gz Install (All Distributions)#

# Download the latest tar.gz archive from the official download page
wget https://aka.ms/download-jdk/microsoft-jdk-17-linux-x64.tar.gz
# Extract to the system JVM directory
sudo tar xzf microsoft-jdk-17-linux-x64.tar.gz -C /usr/lib/jvm/
# Set as default Java runtime
sudo update-alternatives --install /usr/bin/java java /usr/lib/jvm/microsoft-jdk-17*/bin/java 100
sudo update-alternatives --install /usr/bin/javac javac /usr/lib/jvm/microsoft-jdk-17*/bin/javac 100

Post-Installation Verification Steps#

Confirm your installation is working correctly with the following checks:

  1. Check Java runtime version: 
    java -version
    Expected output: 
    openjdk version "17.0.10" 2024-01-16 LTS
OpenJDK Runtime Environment Microsoft-8810159 (build 17.0.10+7-LTS)
OpenJDK 64-Bit Server VM Microsoft-8810159 (build 17.0.10+7-LTS, mixed mode, sharing)
  2. Check Java compiler version: 
    javac -version
# Expected output: javac 17.0.10
  3. Verify JAVA_HOME is set correctly:
    • Windows: echo %JAVA_HOME%
    • macOS/Linux: echo $JAVA_HOME The output should point to the root directory of your Microsoft OpenJDK 17 installation.

Configuration Best Practices#

  1. Environment Variable Management: Add $JAVA_HOME/bin to the start of your PATH variable to avoid conflicts with other installed JDK versions. For per-user installs, set JAVA_HOME in ~/.bashrc, ~/.zshrc (Linux/macOS) or user-level environment variables (Windows).
  2. Version Pinning: In enterprise environments, pin the JDK version to avoid unexpected updates:
    • APT: sudo apt-mark hold msopenjdk-17
    • DNF: sudo dnf versionlock msopenjdk-17
    • Containers: Use explicit image tags like mcr.microsoft.com/openjdk/jdk:17-ubuntu instead of latest
  3. Container Optimization: Use distroless or Alpine-based Microsoft OpenJDK images for smaller attack surfaces, and enable CDS to reduce application startup time by 30-50%. Use -XX:MaxRAMPercentage=75.0 instead of fixed -Xmx values to dynamically adjust heap size based on container memory limits.
  4. **Update Cadence: Apply quarterly CPU updates within 30 days of release to address critical security vulnerabilities. Subscribe to the Microsoft OpenJDK release notes feed for update alerts.
  5. IDE Configuration: In VS Code, IntelliJ, or Eclipse, set your project SDK to Microsoft OpenJDK 17 to leverage ecosystem-specific optimizations. The VS Code Extension Pack for Java automatically detects Microsoft OpenJDK installations.

Example Usage: Building a Java 17 Application#

We will build a simple application that uses Java 17 standard features (sealed classes, records) and preview features (pattern matching for switch):

  1. Create a file ShapeCalculator.java: 
    // Java 17 sealed interface feature
sealed interface Shape permits Circle, Rectangle, Square {}
 
record Circle(double radius) implements Shape {}
record Rectangle(double width, double height) implements Shape {}
record Square(double side) implements Shape {}
 
public class ShapeCalculator {
    public static double calculateArea(Shape shape) {
        // Java 17 preview pattern matching for switch
        return switch (shape) {
            case Circle c -> Math.PI * c.radius() * c.radius();
            case Rectangle r -> r.width() * r.height();
            case Square s -> s.side() * s.side();
        };
    }
 
    public static void main(String[] args) {
        Shape circle = new Circle(5.0);
        Shape rectangle = new Rectangle(4.0, 6.0);
        Shape square = new Square(3.0);
 
        System.out.printf("Circle area: %.2f%n", calculateArea(circle));
        System.out.printf("Rectangle area: %.2f%n", calculateArea(rectangle));
        System.out.printf("Square area: %.2f%n", calculateArea(square));
    }
}
  2. Compile the code with preview features enabled: 
    javac --enable-preview -source 17 ShapeCalculator.java
  3. Run the application: 
    java --enable-preview ShapeCalculator
    Expected output: 
    Circle area: 78.54
Rectangle area: 24.00
Square area: 9.00

Container Deployment Example#

Use the official Microsoft OpenJDK 17 runtime image to package your application:

FROM mcr.microsoft.com/openjdk/jdk:17-ubuntu-runtime
WORKDIR /app
COPY target/shape-calculator.jar .
ENTRYPOINT ["java", "-jar", "shape-calculator.jar"]

Troubleshooting Common Installation Issues#

  1. JAVA_HOME points to the wrong JDK: Manually set JAVA_HOME to the root of your Microsoft OpenJDK 17 installation, and ensure it appears before other Java paths in your PATH variable.
  2. Conflicting Java versions: Use update-alternatives --config java (Linux) or /usr/libexec/java_home -v 17 (macOS) to set Microsoft OpenJDK 17 as the default runtime.
  3. Apple Silicon performance issues: Ensure you installed the ARM64 build of Microsoft OpenJDK 17, not the x64 build which runs via Rosetta emulation.
  4. Legacy application compatibility errors: Use the jdeps tool to identify usage of deprecated or encapsulated APIs, and add --add-opens flags to your runtime command to grant access to required modules.

Migrating to Microsoft OpenJDK 17 from Other Distributions#

Microsoft OpenJDK 17 is a drop-in replacement for any TCK-compliant JDK 17 distribution:

  1. Uninstall your existing JDK (optional, you can run multiple JDKs side-by-side)
  2. Install Microsoft OpenJDK 17 using the steps above
  3. Update all environment variables, IDE configurations, and CI/CD pipeline settings to point to the new JDK
  4. Run your full application test suite to confirm no compatibility issues
  5. Roll out to staging environments first, then production

For migrations from JDK 8 or 11, follow the OpenJDK migration guide to address module system and deprecated API changes, which apply to all JDK 17 distributions.

References#

  1. Official Microsoft OpenJDK Download Page
  2. Microsoft OpenJDK Documentation
  3. OpenJDK 17 Official Release Notes
  4. Microsoft OpenJDK Container Images on MCR
  5. Microsoft OpenJDK Support Lifecycle Policy
2026-05