Skip to main content

Unity Projects Migration

Migrating VRChat Unity Projects from Windows to Nobara Linux​

Moving your avatar projects to Linux is completely doable, but because Unity compiles graphics data differently depending on your operating system, you can't just open a Windows project on Linux without a little prep work.

Here is how to get your Unity workflow running smoothly on Nobara.

1. Installing Unity on Linux​

Fortunately, Unity Hub has a native Linux version.

  • Download Unity Hub (usually available as an AppImage, Flatpak, or via your package manager) and log in.
  • Install the current required Unity version for VRChat (Check the official VRChat documentation for the exact version: https://creators.vrchat.com/sdk/upgrade/current-unity-version/).
  • Important: Make sure to include the Windows Build Support and Android Build Support modules when installing the editor. Even though you are on Linux, you still need to compile your avatars for Windows and Quest users!

2. Installing ALCOM (VCC Replacement)​

The official VRChat Creator Companion (VCC) does not support Linux. ALCOM is a community-built alternative with native Linux support that handles the same tasks — managing VRChat SDK packages, creating projects, and updating dependencies.

  • Download the latest ALCOM release for Linux from GitHub.
  • Launch it and point it to your Unity installation.
  • Use it to manage your VRChat projects just like you would with VCC on Windows.

3. Migrating Your Existing Windows Projects​

If you simply copy your Unity project folder from Windows to Linux and try to open it, everything will look broken (pink textures, flat colors) and your console will be spammed with this error:

State comes from an incompatible keyword space

Why this happens: Unity generated a cache of shaders specifically for Windows (DirectX). Linux uses Vulkan or OpenGL, so those cached files completely break.

The Fix (The "Nuke the Cache" Method):

  1. Ensure Unity is completely closed.
  2. Open your Unity project's root folder in your file manager.
  3. Find the folder named Library and delete it. (You can also delete Temp and Logs if they exist).
  4. Open the project in Unity.
  5. Wait. Unity will rebuild the entire Library folder from scratch, compiling all the shaders specifically for Linux. This can take a long time depending on the size of your project, so grab a snack and let it run.

4. Shader Management (Poiyomi)​

If you use Poiyomi Toon Shader, heavily optimized or "Locked" materials can sometimes struggle during OS migrations.

  • Best Practice: Before moving your project from Windows, go through your avatar and Unlock all Poiyomi materials. If you already migrated to Linux, you can select your materials, right click > Poiyomi > Materials > Unlock.
  • Once the project is safely open and functioning on Linux, you can re-lock them.
  • If a shader still looks broken after deleting the Library folder, find the shader folder (e.g., _PoiyomiShaders) in your Assets window, right-click it, and select Reimport.

5. Sharing Projects Back to Windows Users​

If you are collaborating with friends who are still on Windows, you have two safe ways to share your work without breaking their projects with your Linux cache:

  • Method A: UnityPackage (Highly Recommended) Select your avatar in the Assets folder, right-click, and choose Export Package. This strictly packages your source files (models, textures, unlocked materials) and leaves the Linux-specific caches behind. Your friend can import this directly into their Windows project. (Reminder: Always unlock Poiyomi materials before exporting!)
  • Method B: Zipping the Project Folder If you must send the entire project folder, you must delete the Library folder before zipping it. If you don't, your Windows friend will get the exact same "incompatible keyword space" error you got! Once they extract the zip and open it, their PC will build a fresh Windows cache.