How to Control Hardware Acceleration in draw.io Desktop: Disabling GPU Rendering

draw.io Desktop provides a --disable-acceleration command-line flag that invokes app.disableHardwareAcceleration() in the Electron main process before window creation, forcing the application to use software-based rendering instead of the GPU.

draw.io Desktop is built on the Electron framework, which enables hardware-accelerated rendering by default to improve UI performance. However, GPU acceleration can cause stability issues on systems with incompatible graphics drivers, virtual machines, or when reducing GPU usage is necessary. Understanding how to control draw.io Desktop hardware acceleration allows you to troubleshoot display problems and optimize performance for your specific environment.

How draw.io Desktop Handles Hardware Acceleration

Electron applications like draw.io Desktop use Chromium's rendering engine, which leverages the GPU for compositing and drawing the user interface. By default, hardware acceleration is enabled to ensure smooth diagram rendering and responsive canvas interactions. The acceleration state is determined at process startup in the main Electron process before any renderer windows are instantiated, making it impossible to toggle at runtime.

Disabling Hardware Acceleration with the --disable-acceleration Flag

The application exposes a built-in command-line interface to disable GPU support. When detected, this flag triggers Electron's native API to turn off hardware acceleration for the entire process lifetime, affecting all windows and renderer processes.

Command-Line Usage

Pass the flag after the npm start command using the double hyphen (--) separator to forward arguments to the Electron process:

# From the repository root (after npm install)

npm start -- --disable-acceleration

The double hyphen tells npm to pass the subsequent arguments directly to the Electron process rather than consuming them itself.

Implementation in src/main/electron.js

According to the drawio-desktop source code, the flag detection occurs immediately after Electron module imports in the main process entry point. Lines 46-50 of src/main/electron.js check process.argv for the flag and call the disable method:

// src/main/electron.js
// Command option to disable hardware acceleration
if (process.argv.indexOf('--disable-acceleration') !== -1)
{
    app.disableHardwareAcceleration();
}

This check runs early in the application lifecycle, ensuring app.disableHardwareAcceleration() executes before any BrowserWindow instances are created.

Permanent Configuration and Debugging

For users who consistently need software rendering, hardcoding the flag into a startup script prevents manual entry each session.

Creating a Wrapper Script

You can create a Node.js launcher that spawns the Electron process with the flag automatically appended:

// run-drawio.js
const { spawn } = require('child_process');
const path = require('path');

const drawio = path.join(__dirname, 'node_modules/.bin/electron');
const main = path.join(__dirname, 'src/main/electron.js');

const child = spawn(drawio, [main, '--disable-acceleration'], {
    stdio: 'inherit',
});

child.on('close', code => process.exit(code));

Execute it with node run-drawio.js to always start with GPU acceleration disabled.

Verifying the Acceleration State

To confirm whether the flag was parsed correctly, inspect process.argv directly in the main process:

// Inside any main-process script
const isAccelDisabled = process.argv.includes('--disable-acceleration');
console.log('Hardware acceleration disabled:', isAccelDisabled);

This will log true when the flag is present and false otherwise, useful for debugging startup configurations.

When to Disable GPU Acceleration

Several scenarios warrant disabling hardware acceleration in draw.io Desktop:

• Virtual machines with limited or no GPU passthrough capabilities
• Outdated graphics drivers causing crashes, black screens, or visual artifacts
• Remote desktop environments where GPU redirection is unavailable or buggy
• Battery conservation on laptops needing to reduce GPU utilization
• Compatibility testing to isolate rendering issues between software and hardware paths

Summary

• draw.io Desktop runs on Electron and enables GPU hardware acceleration by default for UI rendering.
• Use the --disable-acceleration flag to force software rendering when encountering graphics issues.
• The flag is processed in src/main/electron.js by calling app.disableHardwareAcceleration() before any browser windows are created.
• Create a Node.js wrapper script to permanently disable acceleration without typing the flag manually.
• This setting applies to the entire process lifetime and cannot be changed after the application starts.

Frequently Asked Questions

What is the exact command to disable hardware acceleration in draw.io Desktop?

Launch the application with npm start -- --disable-acceleration from the repository root, or append --disable-acceleration directly to the Electron executable when running a packaged build. This passes the flag to the main process where it triggers app.disableHardwareAcceleration() before window initialization.

Where in the source code is hardware acceleration disabled?

The check resides in src/main/electron.js at lines 46-50. The code searches process.argv for --disable-acceleration and calls app.disableHardwareAcceleration() if found, ensuring the setting applies before any browser windows open.

Can I disable hardware acceleration permanently without typing the flag each time?

Yes. Create a Node.js wrapper script that spawns the Electron process with --disable-acceleration prepopulated in the argument array, or modify your desktop shortcut to include the flag. The setting must be applied at process startup and cannot be toggled at runtime.

Why would I need to turn off GPU acceleration in draw.io Desktop?

Disable it to resolve rendering glitches, black screens, or crashes caused by incompatible graphics drivers, or when running in virtual machines and remote desktop sessions without proper GPU support. Software rendering ensures compatibility at the cost of slightly higher CPU usage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}