funwithlinux blog

How to Fix '.NETFramework 4.7.1 Reference Assemblies Not Found' Error in Unity3D with VSCode on Ubuntu Linux

If you’re a Unity3D developer working on Ubuntu Linux and using VSCode as your code editor, you may have encountered the frustrating error: “.NETFramework 4.7.1 Reference Assemblies Not Found”. This error typically arises because Unity relies on Microsoft’s .NET Framework (a Windows-only technology) for scripting, and Linux systems like Ubuntu lack native support for .NET Framework reference assemblies. Without these assemblies, VSCode’s IntelliSense fails, and you may face compilation issues in your Unity projects.

This guide will walk you through resolving this error step-by-step, ensuring your Unity project works seamlessly with VSCode on Ubuntu. We’ll cover prerequisites, core fixes, alternative solutions, and troubleshooting tips.

2025-12

Table of Contents#

  1. Understanding the Error
  2. Prerequisites
  3. Step-by-Step Fix
  4. Alternative Solutions
  5. Conclusion
  6. References

Understanding the Error#

The “.NETFramework 4.7.1 Reference Assemblies Not Found” error occurs because:

  • Unity uses .NET Framework 4.7.1 (or earlier) for legacy scripting support.
  • .NET Framework is a Windows-only runtime; Ubuntu/Linux does not ship with its reference assemblies (e.g., System.dll, mscorlib.dll).
  • VSCode’s C# extension (powered by OmniSharp) relies on these assemblies to provide IntelliSense, syntax highlighting, and error checking. Without them, OmniSharp cannot resolve .NET Framework types, leading to the error.

Prerequisites#

Before proceeding, ensure you have the following installed:

  • Unity3D: Version 2018.1 or newer (supports .NET 4.x scripting runtime).
  • VSCode: Installed via Ubuntu Software Center or snap install code --classic.
  • VSCode C# Extension: Install from the VSCode Marketplace (ms-dotnettools.csharp).
  • Terminal Access: To run commands (Ubuntu’s default terminal or Terminator).

Step-by-Step Fix#

Step 1: Install Mono (for .NET Framework Compatibility)#

Mono is an open-source implementation of .NET Framework, providing partial compatibility on Linux. It includes some reference assemblies, which Unity and VSCode can use.

Install Mono:
Open a terminal and run:

sudo apt update && sudo apt install mono-complete -y
  • mono-complete installs all Mono components (runtime, compilers, and reference assemblies).

Verify Installation:
Check Mono version with:

mono --version

You should see output like Mono JIT compiler version 6.8.0.105 (or newer).

Step 2: Configure Unity’s Scripting Settings#

Ensure Unity uses the .NET 4.x runtime, which aligns with the missing reference assemblies.

  1. Open your Unity project.

  2. Go to Edit > Project Settings > Player.

  3. In the Other Settings tab (under “Configuration”):

    • Scripting Runtime Version: Set to .NET 4.x Equivalent (not “.NET Standard 2.0”).
    • Scripting Backend: Use Mono (IL2CPP is less compatible with Linux).
    • Api Compatibility Level: Set to .NET Framework 4.x.

    Unity Scripting Settings
    Fig 1: Unity’s Player Settings for .NET 4.x

  4. Click Apply to save changes. Unity will regenerate project files (.csproj, .sln).

Step 3: Install .NETFramework 4.7.1 Reference Assemblies via NuGet#

Mono may not include all .NET 4.7.1 reference assemblies. To fill gaps, use NuGet (the .NET package manager) to install the official Microsoft reference assemblies.

Install NuGet CLI:
If you don’t have NuGet, install it via:

sudo apt install nuget -y

Download Reference Assemblies:

  1. Navigate to your Unity project’s root folder in the terminal. For example: 
    cd ~/UnityProjects/MyProject
  2. Run the following NuGet command to install .NET 4.7.1 reference assemblies: 
    nuget install Microsoft.NETFramework.ReferenceAssemblies.net471 -OutputDirectory packages
    • This downloads the Microsoft.NETFramework.ReferenceAssemblies.net471 package (official Microsoft reference assemblies) into a packages folder in your project.

Step 4: Update Project Configuration#

Unity generates .csproj (C# project) files, but these may not reference the NuGet-installed assemblies. We’ll manually update the configuration to point to the new assemblies.

Option A: Update the .csproj File#

  1. In your Unity project, navigate to the Library folder (hidden by default; enable “Show Hidden Files” in your file manager).

  2. Locate your project’s .csproj file (e.g., MyProject.csproj or Assembly-CSharp.csproj).

  3. Open the .csproj file in VSCode.

  4. Add the following <ItemGroup> section before the closing </Project> tag:

    <ItemGroup>
  <!-- Reference assemblies from NuGet package -->
  <Reference Include="*">
    <HintPath>../packages/Microsoft.NETFramework.ReferenceAssemblies.net471/ref/net471/*.dll</HintPath>
  </Reference>
</ItemGroup>
    • This tells MSBuild (used by OmniSharp) to load all .dll reference assemblies from the NuGet package.

    Note: If Unity regenerates the .csproj file (e.g., after adding scripts), you may need to re-add this section.

Option B: Configure OmniSharp (Alternative to Editing .csproj)#

If editing .csproj is cumbersome, configure OmniSharp (VSCode’s C# backend) to use the NuGet assemblies directly:

  1. In your Unity project, create a .vscode folder (if it doesn’t exist): 
    mkdir -p ~/UnityProjects/MyProject/.vscode
  2. Create an omnisharp.json file in .vscode: 
    nano ~/UnityProjects/MyProject/.vscode/omnisharp.json
  3. Add the following content and save (Ctrl+O, Enter, Ctrl+X): 
    {
  "msbuild": {
    "referenceAssembliesPath": "./packages/Microsoft.NETFramework.ReferenceAssemblies.net471/ref/net471/"
  }
}
    • This tells OmniSharp to look for reference assemblies in the NuGet package folder.

Step 5: Verify and Restart Tools#

  1. Restart VSCode: Close and reopen VSCode to reload OmniSharp.
  2. Check OmniSharp Log:
    • Open VSCode’s Output panel (Ctrl+Shift+U).
    • Select “OmniSharp Log” from the dropdown.
    • Look for messages like Successfully loaded project or Reference assemblies loaded. If you see errors about missing assemblies, double-check the omnisharp.json path or .csproj edits.
  3. Test IntelliSense: Open a C# script in VSCode (e.g., PlayerController.cs). Type using System;—IntelliSense should resolve System without errors.

Alternative Solutions#

Alternative 1: Copy Assemblies from a Windows Machine#

If NuGet fails, copy .NET 4.7.1 reference assemblies from a Windows PC:

  1. On Windows, navigate to:
    C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.1
  2. Copy the entire v4.7.1 folder to your Ubuntu machine (e.g., via USB or cloud storage).
  3. Place it in ~/UnityProjects/MyProject/packages/ (or any path).
  4. Update .csproj or omnisharp.json to point to this folder (e.g., <HintPath>../packages/v4.7.1/*.dll</HintPath>).

Alternative 2: Use .NET 5+ (Modern Approach)#

If your project allows, migrate to .NET 5+ (cross-platform) instead of .NET Framework:

  1. In Unity’s Player Settings, set Api Compatibility Level to .NET Standard 2.1 or .NET 5+.
  2. Update scripts to use .NET 5+ APIs (most .NET Framework code is compatible).
  3. This avoids reliance on Windows-only reference assemblies.

Conclusion#

The “.NETFramework 4.7.1 Reference Assemblies Not Found” error in Unity3D on Ubuntu is caused by missing Windows-only .NET Framework assemblies. By combining Mono for base compatibility, NuGet for official reference assemblies, and configuration tweaks, you can resolve the error and restore VSCode’s IntelliSense.

For long-term projects, consider migrating to .NET 5+ for cross-platform support. For legacy projects, the NuGet + OmniSharp fix outlined above is reliable.

References#