envycontrol

Switch between different GPU modes

$ sudo envycontrol [[-s|--switch]] [nvidia|integrated|hybrid]

$ envycontrol --dm

$ sudo envycontrol [[-q|--query]]

$ sudo envycontrol --reset

$ envycontrol [[-h|--help]]

$ envycontrol [[-v|--version]]

envycontrol [-s | --switch ] [-q | --query] [-v | --version] [-h | --help] [--force] [--no-grub-update] [--reboot]

Where <mode> can be one of: integrated, nvidia, hybrid, compute.

-s, --switch
    Switches the GPU operating mode to the specified <mode>. Requires a system reboot to apply changes.

-q, --query
    Displays the current active GPU operating mode and configuration status.

-v, --version
    Shows the version information of envycontrol.

-h, --help
    Displays a help message with available commands and options.

--force
    Forces a mode switch even if envycontrol believes it's unnecessary or already in effect. Use with caution.

--no-grub-update
    Prevents envycontrol from updating the GRUB bootloader configuration after a mode switch. Use if GRUB is managed externally.

--reboot
    Immediately reboots the system after a successful mode switch to apply changes. Often a required step.


    The target GPU mode: 'integrated', 'nvidia', 'hybrid', or 'compute'. Used with --switch.

envycontrol is a command-line utility designed to simplify the management of NVIDIA GPUs, particularly on Linux laptops equipped with NVIDIA Optimus or hybrid graphics technology.

These laptops typically feature both an integrated graphics processor (iGPU), usually from Intel or AMD, and a dedicated NVIDIA discrete graphics processor (dGPU).

The primary purpose of envycontrol is to facilitate easy switching between different GPU operating modes, which can significantly impact power consumption and performance. It abstracts away the complexities of manually configuring Xorg and display managers.

Common modes supported include:
• Integrated: Only the iGPU is active, providing maximum power efficiency but lower graphics performance. The dGPU is powered off.
• NVIDIA: Only the dGPU is active, offering full graphics performance but consuming more power.
• Hybrid: Both GPUs are active. The iGPU typically drives the display, and the dGPU can render applications via technologies like NVIDIA Prime Render Offload.
• Compute: Similar to NVIDIA mode, but optimized for compute workloads (e.g., CUDA, OpenCL) where display output is not the primary concern.

After switching modes, envycontrol typically requires a system reboot for the changes to take full effect, as it modifies fundamental display server configurations. It is a community-driven tool often used as a front-end for more complex underlying systems like optimus-manager.

• Reboot Required: Most mode switches necessitate a system reboot to apply changes, affecting workflow.
• Laptop Specific: Primarily designed for laptops with NVIDIA Optimus/hybrid graphics. Its utility is limited on desktop systems or laptops with only a single GPU.
• Dependency on Drivers & Xorg: Proper functioning depends on correct NVIDIA driver installation, Xorg server configuration, and display manager setup.
• Third-Party Tool: envycontrol is a community-developed tool, not officially supported by NVIDIA or major Linux distributions. It might interact with underlying system components (like optimus-manager) which also need to be correctly set up.
• Potential Conflicts: Using envycontrol alongside other GPU management utilities (e.g., prime-select or manual Xorg edits) can lead to conflicts or unpredictable behavior.

envycontrol primarily works by modifying system configuration files, most notably those related to the Xorg display server. Depending on the specific setup and underlying tools (like optimus-manager), it might:

• Create or modify files in /etc/X11/xorg.conf.d/ to dictate which GPU the X server should use or how Prime Render Offload should be configured.
• Adjust kernel parameters or GRUB boot options to ensure the correct GPU is initialized early in the boot process.
• Interact with bbswitch or acpi_call to manage power to the discrete GPU.
• Configure display managers like GDM, LightDM, or SDDM to properly load the chosen GPU setup.

envycontrol supports several distinct GPU modes, each with specific implications for performance and power consumption:

• `integrated` (iGPU-only): The NVIDIA dGPU is completely powered off, and all display output is handled by the integrated graphics (e.g., Intel UHD, AMD Radeon Vega). This mode offers the best battery life and produces the least heat, ideal for general productivity tasks.

• `nvidia` (dGPU-only): The NVIDIA dGPU is fully active and directly drives the display. This mode provides maximum graphics performance, essential for gaming or demanding applications. However, it consumes significantly more power and generates more heat.

• `hybrid` (Prime Render Offload): Both GPUs are active. The integrated GPU drives the primary display, while the NVIDIA dGPU can be selectively used to render specific applications (e.g., games, 3D software) and offload their output to the iGPU for display. This is achieved via NVIDIA Prime Render Offload and offers a balance between performance and power, allowing the dGPU to be powered down when not in use.

• `compute` (dGPU for CUDA/OpenCL): Similar to nvidia mode in terms of the dGPU being active, but often configured specifically for compute workloads where display output is not the primary concern. It might involve disabling Xorg for the dGPU to free up resources or enable specialized drivers for compute tasks like CUDA or OpenCL development.

envycontrol emerged as a solution to simplify the complex process of switching GPU modes on Linux laptops with NVIDIA Optimus technology. Before such tools, users often had to manually edit Xorg configuration files, which was error-prone and tedious.

While optimus-manager was a significant step forward, envycontrol aims to provide an even more streamlined, user-friendly command-line interface, sometimes acting as a wrapper or complementary tool to optimus-manager or similar underlying mechanisms. Its development has been driven by the Linux community's need for robust and easy-to-use hybrid graphics management, particularly prevalent in distributions favored by power users like Arch Linux. It is not part of the official NVIDIA driver suite but a testament to community-driven solutions for specific hardware challenges on Linux.

optimus-manager(1), prime-select(1), xrandr(1), nvidia-smi(1), lspci(8)