DOCSEARCHbyAlgolia
Submit Docs

EnvyControl

repository·main·Indexed 23 days ago

https://github.com/bayasdev/envycontrol

A CLI tool for Linux that simplifies switching between GPU modes (Integrated, Hybrid, and Nvidia) on Nvidia Optimus laptops to balance battery life and graphical performance. It supports various distributions including Arch Linux, Fedora, Ubuntu, Debian, and NixOS, and provides options for RTD3 power management, ForceCompositionPipeline, and Coolbits configuration.

Tokens
1.4K
Snippets
8
Records
12
Agent score
34%

What's inside EnvyControl

  1. Install EnvyControl on various Linux distributions

    main

    EnvyControl can be installed using several methods depending on your distribution:

    Arch Linux

    Use the AUR:

    yay -S envycontrol

    Fedora / OSTree Distros (Silverblue, Kinoite, etc.)

    Use the COPR repository maintained by @sunwire:

    sudo dnf copr enable sunwire/envycontrol
sudo dnf install python3-envycontrol

    Note for OSTree: After enabling the repo, run rpm-ostree cleanup -m and then rpm-ostree install python-envycontrol, followed by a reboot.

    Ubuntu / Debian

    Install the provided .deb package to avoid PEP668 issues:

    1. Download python3-envycontrol_version.deb from the releases page.
    2. Install it:
    sudo apt -y install ./python3-envycontrol_version.deb

    NixOS

    Using Nix Flakes, you can run it directly:

    nix run github:bayasdev/envycontrol -- <args>

    Or add it to your configuration inputs and packages.

    From Source

    Clone the repository and run the script directly:

    git clone https://github.com/bayasdev/envycontrol.git
python ./envycontrol.py -s <MODE>

    (Use python3 on Ubuntu/Debian).

    To install globally via pip:

    sudo pip install .

  2. Enable Wayland session on Gnome 43+

    main

    Gnome 43+ requires the NVreg_PreserveVideoMemoryAllocations kernel parameter, which can break sleep in nvidia and hybrid modes. If you need to enable a Wayland session, run the following commands to enable Nvidia services and disable the GDM rule that EnvyControl manages:

    sudo systemctl enable nvidia-{suspend,resume,hibernate}
sudo ln -s /dev/null /etc/udev/rules.d/61-gdm.rules

  3. Switch GPU graphics modes with EnvyControl

    main

    Use the -s or --switch flag to change the system's graphics mode. A reboot is required for changes to take effect.

    Available Modes

    • integrated: Uses only the integrated Intel or AMD iGPU. The Nvidia dGPU is turned off to save battery. External screens wired to the dGPU may not work.
    • hybrid: Enables PRIME render offloading. The dGPU can be dynamically turned off using RTD3 power management (Turing architecture or later).
    • nvidia: Uses the Nvidia dGPU exclusively. Provides higher performance and is recommended for external screen usage. Wayland sessions default to this mode.

    Usage Examples

    Set to integrated mode:

    sudo envycontrol -s integrated

    Set to hybrid mode with fine-grained power control:

    sudo envycontrol -s hybrid --rtd3

    Set to nvidia mode with ForceCompositionPipeline and Coolbits (value 24):

    sudo envycontrol -s nvidia --force-comp --coolbits 24

    Set to nvidia mode with a specific Display Manager (e.g., LightDM):

    sudo envycontrol -s nvidia --dm lightdm
    sudo envycontrol -s integrated

  5. Manually uninstall EnvyControl files

    main

    If EnvyControl is uninstalled and these files were not removed automatically, you should remove them manually to prevent incorrect system behavior:

    • /var/cache/envycontrol
    • /etc/modprobe.d/blacklist-nvidia.conf
    • /lib/udev/rules.d/50-remove-nvidia.rules
    • /lib/udev/rules.d/80-nvidia-pm.rules
    • /etc/X11/xorg.conf
    • /etc/X11/xorg.conf.d/10-nvidia.conf
    • /etc/modprobe.d/nvidia.conf

  6. Configure Hybrid mode RTD3 power management

    main

    In hybrid mode, you can manage PCI-Express Runtime D3 (RTD3) power management for Turing and later architectures using the --rtd3 [VALUE] flag.

    Available values:

    • 0: Disabled
    • 1: Coarse-grained
    • 2: Fine-grained (Default)
    • 3: Fine-grained for Ampere and later

    Example:

    sudo envycontrol -s hybrid --rtd3
    sudo envycontrol -s hybrid --rtd3

  7. Configure Nvidia mode options (ForceCompositionPipeline and Coolbits)

    main

    When using nvidia mode, you can use specific flags to improve visual performance or enable overclocking:

    • --force-comp: Enables ForceCompositionPipeline to fix screen tearing.
    • --coolbits [VALUE]: Enables Nvidia Coolbits for overclocking. The default value is 28. You can specify a custom value (e.g., --coolbits 24).
    sudo envycontrol -s nvidia --force-comp --coolbits 24

  8. Manage EnvyControl cache for mode transitions

    main

    EnvyControl uses a cache to store the Nvidia PCI bus ID. This allows for direct transitions from integrated mode to nvidia mode. The cache is automatically created when switching away from hybrid mode.

    Cache Details:

    • Location: /var/cache/envycontrol/cache.json
    • Format: {"nvidia_gpu_pci_bus": "PCI:1:0:0"}

    Commands:

    • Create cache (Must be in hybrid mode):
      sudo envycontrol --cache-create
    - **Query cache**:
  ```bash
sudo envycontrol --cache-query
    • Delete cache:
      sudo envycontrol --cache-delete
    sudo envycontrol --cache-create