Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Usage

Querying GPUs

To have cardwire list all detected GPUs, use:

cardwire list

For each detected GPU, the command will return:

  • An identifier (ID). These are used for manual blocking and unblocking.
  • The GPU’s name (NAME)
  • The GPU’s PCI address (PCI)
  • The associated render node (RENDER)
  • The associated device node (CARD)
  • Whether the GPU has been identified as the default GPU (DEFAULT). Default GPUs will remain available when cardwire is set to integrated.
  • Whether the GPU is a discrete GPU (DISCRETE)
  • Whether the GPU is currently blocked (BLOCKED)

--json prints the full device map as JSON. --full prints the full pci device map as JSON.

Example:

$ cardwire list
ID  NAME                                         PCI           RENDER      CARD   DEFAULT  DISCRETE  BLOCKED
--  -------------------------------------------  ------------  ----------  -----  -------  --------  -------
0   Rembrandt [Radeon 680M]                      0000:07:00.0  renderD129  card2  (*)      ( )       false
1   Navi 23 [Radeon RX 6650 XT / 6700S / 6800S]  0000:03:00.0  renderD128  card1  ( )      (*)       true

Mode switching

To print the current mode:

cardwire get

GPU modes can be switched using the cardwire set command.

Integrated

To have cardwire block the dGPU, use:

cardwire set integrated

Note

The block only applies to new launched apps. Apps that are already running will keep using the GPU until you restart them. Restarting can help.

Tip

The dedicated GPU can still power down even if your desktop has it open, as long as nothing is actively using it. To double-check, run: cardwire gpu 1 --lsof

Hybrid

To have cardwire allow access to all GPUs, use

cardwire set hybrid

Smart Mode

Smart mode blocks the dedicated GPU by default like integrated mode, but uses a real-time analyzer to scan each application at launch and selectively allow GPU access for approved apps.

Cardwire natively integrates with desktop environments (GNOME, KDE) via a Switcheroo DBus shim. This means you can simply right-click an application in your app launcher and select “Launch using Discrete Graphics Card”, and Cardwire will automatically unblock the GPU for that application.

Tip

When an application is launched via the Switcheroo UI or with CARDWIRE_FORCE_DGPU=1, Cardwire will hide the integrated GPU (iGPU) from the app. The app will only be able to see and use the dedicated GPU, guaranteeing it runs on the correct hardware.

When launching apps in Smart mode, cardwire checks for the following to allow the dGPU:

  • CARDWIRE_ALLOW=1 env var (highest priority, unblocks the GPU but doesn’t force the app to use it)
  • CARDWIRE_FORCE_DGPU=1 env var (unblocks the GPU, forces the app to use it, and completely hides the iGPU)
  • CARDWIRE_FORCE_GPU=<gpu_id> env var (unblocks a specific GPU and forces the app to use it)
  • Steam games, identified by SteamAppId, are discovered into the internal application list and blocked by default until allowed
  • The per-app policies stored in cardwire’s internal application list

Note

The former auto-approval inputs are deprecated in favor of the internal application list. Steam auto-allow, PrefersNonDefaultGpu desktop entries and the automatic approval of GPU environment variables (DRI_PRIME, __NV_PRIME_RENDER_OFFLOAD) are no longer evaluated.

cardwire set smart

Note

This feature is a work in progress. The detection methods will be improved in future updates.

Manual

Important

To prevent system breakage, cardwire will not block the default GPU, even when explicitly instructed to do so.

If more granular control over several GPUs is required, cardwire also allows manually blocking individual GPUs by ID. To do so, it needs to be set to manual mode:

cardwire set manual

Once set to manual, GPU states can then be set by ID. To find the correct ID, see Querying GPUs.

To block the GPU with ID 1:

cardwire gpu 1 --block

To unblock:

cardwire gpu 1 --unblock

Launching apps on a specific GPU

cardwire launch starts a program with the right GPU environment set, without switching modes:

cardwire launch --gpu 1 nvtop
cardwire launch glxgears

Without --gpu, cardwire picks the best GPU for the job, in this order: a discrete non-default GPU, a discrete GPU, the default GPU, then the first available one. The command fetches the launch environment from the daemon.

Launching on a blocked or unavailable GPU is refused with a clear error, switch to Smart mode or unblock the GPU first.

System information

To check that the daemon is running:

cardwire manager status

To refresh the GPU list held by the daemon (useful after a hotplug event):

cardwire debug refresh-gpu

To check the power state of a GPU (for example whether it reached D3Cold):

cardwire gpu 1 --power

Configuration

Experimental Nvidia Block

Note

This setting is experimental because it tells cardwire to block specific Nvidia files, such as /dev/nvidiactl, that can be shared across multiple Nvidia GPUs. For this reason, it only works reliably on systems with exactly two GPUs: one integrated GPU and one dedicated Nvidia GPU.

Tip

Even though it is experimental, enabling this setting is recommended. It helps prevent unwanted GPU wakeups from Vulkan apps (GTK on gnome) and from tools that use /dev/nvidiactl, such as nvtop

To get if experimental Nvidia block is enabled:

cardwire config experimental-nvidia-block

To enable/disable it:

cardwire config experimental-nvidia-block true

Battery Auto Switch Mode

Cardwire can automatically switch GPU modes when the system switches between battery and AC power. When battery_auto_switch is enabled, cardwire switches to integrated mode on battery and back to a configurable mode when on AC power.

To get if battery auto switch is enabled:

cardwire config battery-auto-switch

To enable/disable it:

cardwire config battery-auto-switch true

The mode cardwire switches to on AC power is controlled by battery_auto_switch_mode. This can be set to integrated, hybrid, manual, or smart.

To get the current battery auto switch mode:

cardwire config battery-auto-switch-mode

To set the battery auto switch mode:

cardwire config battery-auto-switch-mode hybrid

External Display Auto Switch

When an external display is connected to a port wired directly to the dedicated GPU, Cardwire can temporarily switch Integrated and Smart modes to Hybrid. It restores the requested mode after the display is disconnected.

This feature is disabled by default. To get if external display auto switch is enabled:

cardwire config external-display-auto-switch

To enable/disable it:

cardwire config external-display-auto-switch true

Auto Apply Gpu State

When you switch back to manual mode, this setting automatically restores the GPU states you had set before. These saved states are stored in /var/lib/cardwire/gpu_state.json

To view the current saved states, run:

cat /var/lib/cardwire/gpu_state.json

Example output:

{
  "0000:03:00.0": {
    "block": false
  },
  "0000:07:00.0": {
    "block": false
  }
}

In this example, both GPUs are set to allow access (block: false) when manual mode is restored

To get the current setting:

cardwire config auto-apply-gpu-state

To set the setting:

cardwire config auto-apply-gpu-state true