Upgrading from Antigravity IDE 1.x to Antigravity 2.x is a major architectural transition. In the 2.x generation, the core environment has shifted to a robust, standalone, agentic workspace, while retaining a sibling editor package (Antigravity IDE) that houses all your familiar VS Code extensions, settings, and workflows.
If you are a Linux user transitioning to 2.x using the .tar.gz archive, you might encounter common friction points such as Chromium sandbox errors or missing desktop integration/taskbar grouping.
This guide walks you through the entire migration process and solves these issues once and for all.
1. Back Up Your Data (Don't Skip!)
Before modifying anything, back up your existing settings, extensions, and chat history.
Open your terminal and run:
cp -r ~/.gemini/antigravity ~/.gemini/antigravity-backup-manual
──────
2. Install Antigravity IDE 2.x from .tar.gz
If you are installing the new version from a .tar.gz archive, here is the standard system integration workflow:
A. Extract and Move to /opt
Extract the archive and move the directory to /opt for system-wide access:
tar -xvzf Antigravity-IDE.tar.gz
sudo mv Antigravity-IDE /opt/antigravity-ide
B. Fix the Chrome Sandbox Permission Error
When launching the IDE for the first time, you might see this common Electron/Chromium crash error:
FATAL:setuid_sandbox_host.cc] The SUID sandbox helper binary was found, but is not configured correctly. ... You need to make sure that /opt/antigravity-ide/chrome-sandbox is owned by root and has mode 4755.
Fix this by setting the correct owner and SUID permission on the sandbox binary:
sudo chown root:root /opt/antigravity-ide/chrome-sandbox
sudo chmod 4755 /opt/antigravity-ide/chrome-sandbox
──────
3. Remove Old 1.x Files
Once you have verified that version 2.x is functioning, you can safely clean up your old 1.x installation files:
sudo apt remove antigravity
sudo rm -rf /path/to/antigravity-ide-old
──────
4. Fix Duplicate & Blank Taskbar Icons (Desktop Integration)
If you launch the IDE and find that a new, iconless program window opens separately in your dock rather than grouping under your pinned shortcut, the system cannot match your .desktop file to the running application's window class name ( WM_CLASS ).
To resolve this, update your desktop shortcut with the correct StartupWMClass.
A. Create or Edit the Shortcut File
Create a new desktop entry in your local applications directory:
nano ~/.local/share/applications/antigravity.desktop
B. Paste this Optimized Configuration
Ensure the StartupWMClass is set exactly to antigravity-ide (all lowercase):
[Desktop Entry]
Name=Antigravity
Comment=Experience liftoff
GenericName=Text Editor
Exec=/opt/antigravity-ide/antigravity-ide %F
Icon=/opt/antigravity-ide/resources/app/resources/linux/code.png
Type=Application
StartupNotify=false
StartupWMClass=antigravity-ide
Categories=TextEditor;Development;IDE;
MimeType=application/x-antigravity-workspace;
Actions=new-empty-window;
Keywords=vscode;
[Desktop Action new-empty-window]
Name=New Empty Window
Exec=/opt/antigravity-ide/antigravity-ide --new-window %F
Icon=/opt/antigravity-ide/resources/app/resources/linux/code.png
C. Refresh Desktop Database
Apply the changes instantly so the launcher updates your application menu:
update-desktop-database ~/.local/share/applications/
Final Step: Unpin any old icons from your dock or taskbar, restart the IDE from your applications menu, and pin the active window. It will now group cleanly under a single high-resolution icon!
