Optimus made easy

👁‍🗨 EnvyControl

EnvyControl is a CLI tool that provides an easy way to switch between GPU modes on Nvidia Optimus systems (i.e laptops with hybrid Intel + Nvidia or AMD + Nvidia graphics configurations) under Linux.

📖 License

EnvyControl is free and open-source software released under the MIT license.

⚠️ Disclaimer

This software is provided 'as-is' without any express or implied warranty.

Keep in mind any custom X.org configuration may get deleted or overwritten when switching modes.

✨ Features

• 🐍 Written in Python 3+ for portability and compatibility
• 🐧 Works across all major Linux distros (tested distros)
• 🖥️ Supports GDM, SDDM and LightDM display managers (manual setup instructions also available)
• 🔋 Save battery with integrated graphics mode
• 💻 PCI-Express Runtime D3 (RTD3) Power Management support for Turing and later
• 🎮 Coolbits support for GPU overclocking
• 🔥 Fix screen tearing with ForceCompositionPipeline

📖 Graphics modes

Integrated

• The integrated Intel or AMD iGPU is used exclusively
• Nvidia dGPU is turned off to reduce power consumption
• External screens cannot be used if the video ports are wired to the dGPU

Hybrid

• Enables PRIME render offloading
• RTD3 allows the dGPU to be dynamically turned off when not in use
  • Available choices for the --rtd3 flag (based on the official documentation)
    • 0 disabled
    • 1 coarse-grained
    • 2 fine-grained (default value if you don't provide one)
    • 3 fine-grained for Ampere and later
  • Only works in Turing and later
• Performance on external screens might be reduced

Nvidia

• The Nvidia dGPU is used exclusively
• Higher graphical performance and higher power consumption
• Recommended when working with external screens
  • If facing screen tearing enable ForceCompositionPipeline with the --force-comp flag
• Allows overlocking (not recommended) with the --coolbits flag
  • The default value is 28 bits however it can be manually adjusted according to this guide
• Wayland sessions default to hybrid mode

⚡️ Usage

usage: envycontrol.py [-h] [-v] [-q] [-s MODE] [--dm DISPLAY_MANAGER] [--force-comp] [--coolbits [VALUE]] [--rtd3 [VALUE]] [--reset-sddm] [--reset] [--verbose]

options:
  -h, --help            show this help message and exit
  -v, --version         Output the current version
  -q, --query           Query the current graphics mode
  -s MODE, --switch MODE
                        Switch the graphics mode. Available choices: integrated, hybrid, nvidia
  --dm DISPLAY_MANAGER  Manually specify your Display Manager for Nvidia mode. Available choices: gdm, gdm3, sddm, lightdm
  --force-comp          Enable ForceCompositionPipeline on Nvidia mode
  --coolbits [VALUE]    Enable Coolbits on Nvidia mode. Default if specified: 28
  --rtd3 [VALUE]        Setup PCI-Express Runtime D3 (RTD3) Power Management on Hybrid mode. Available choices: 0, 1, 2, 3. Default if specified: 2
  --use-nvidia-current  Use nvidia-current instead of nvidia for kernel modules
  --reset-sddm          Restore default Xsetup file
  --reset               Revert changes made by EnvyControl
  --cache-create        Create cache used by EnvyControl; only works in hybrid mode
  --cache-delete        Delete cache created by EnvyControl
  --cache-query         Show cache created by EnvyControl
  --verbose             Enable verbose mode

Some examples

Set graphics mode to integrated:

sudo envycontrol -s integrated

Set graphics mode to hybrid and enable fine-grained power control:

sudo envycontrol -s hybrid --rtd3

Set graphics mode to nvidia, enable ForceCompositionPipeline and Coolbits with a value of 24:

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

Set current graphics mode to nvidia and specify to setup LightDM display manager

sudo envycontrol -s nvidia --dm lightdm

Query the current graphics mode:

envycontrol --query

Revert all changes made by EnvyControl:

sudo envycontrol --reset

Caching added with 3.4.0

A cache was added in version 3.4.0. The main purpose is to cache the Nvidia PCI bus ID so that a transition from integrated mode directly to nvidia mode is possible. A reboot is required as usual so the changes can take effect.

Cache file location

Note that these are just helpers to accomodate maintenance tasks. The cache is created automatically whenever switching away from hybrid mode - to integrated or nvidia mode.

CACHE_FILE_PATH = '/var/cache/envycontrol/cache.json'

File format

{
  "nvidia_gpu_pci_bus": "PCI:1:0:0"
}

The cache is automatically re-created whenever a switch from hybrid mode is performed.

Caching command line examples

Create cache used by EnvyControl; only works in hybrid mode

sudo envycontrol --cache-create

When create cache is called when the system is in integrated or nvidia modes

sudo envycontrol --cache-create
...
ValueError: --cache-create requires that the system be in the hybrid Optimus mode

Delete cache created by EnvyControl

sudo envycontrol --cache-delete

Show cache created by EnvyControl

sudo envycontrol --cache-query

⬇️ Getting EnvyControl

Arch Linux (AUR)

1. yay -S envycontrol
2. Run sudo envycontrol -s <MODE> to switch graphics modes

Fedora

Use the COPR maintained by @sunwire

1. Enable the repository with sudo dnf copr enable sunwire/envycontrol
2. sudo dnf install python3-envycontrol
3. Run sudo envycontrol -s <MODE> to switch graphics modes

Enterprise Linux + EPEL 9 (RHEL 9, Rocky Linux 9, CentOS Stream 9, Alma Linux 9 etc.)

Use the COPR maintained by @thonkdifferent

1. Enable the repository with sudo dnf copr enable thonkdifferent/envycontrol
2. sudo dnf install python3-envycontrol
3. Run sudo envycontrol -s <MODE> to switch graphics modes

Ubuntu / Debian

Since PEP668 adoption is no longer possible to install pip packages outside a virtual environment, instead use the provided deb package:

1. Go to the latest release page
2. Download the attached python3-envycontrol_version.deb package
3. Install it with sudo apt -y install ./python3-envycontrol_version.deb
4. Run sudo envycontrol -s <MODE> to switch graphics modes

Nixos

If you're using Nix Flakes:

• Script could be executed using this command:

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

• For system-wide installation, add this flake to inputs in your configuration:

inputs = {
  # ...
  envycontrol.url = github:bayasdev/envycontrol
};

And mention it in the packages like this:

envycontrol.packages.x86_64-linux.default

Thanks to @ITesserakt for adding initial NixOS support!

OSTree Distros (Silverblue, Kinoite, Bazzite, etc.)

These distributions are also supported by the same COPR repo as Fedora Workstation. Use the COPR maintained by @sunwire.

1. Enable the COPR by downloading the .repo file from the COPR page, linked above. Put the .repo file in /etc/yum.repos.d.
2. Clean package cache with rpm-ostree cleanup -m.
3. Overlay the package with rpm-ostree install python-envycontrol.
4. Reboot to apply the overlay.
5. Use EnvyControl with sudo envycontrol -s <MODE>

From source

1. Clone this repository with git clone https://github.com/bayasdev/envycontrol.git or download the latest tarball from the releases page
2. Run the script from the root of the repository like this python ./envycontrol.py -s <MODE>

💡 Replace python with python3 on Ubuntu/Debian

Install globally as a pip package

• From the root of the cloned repository run sudo pip install .
• Now you can run sudo envycontrol -s <MODE> from any directory to switch graphics modes.

👕 GUIs

Gnome Extension

The GPU profile selector extension provides a simple way to switch between graphics modes in a few clicks, you can get it from here.

Make sure to have EnvyControl installed globally!

KDE Widget

Optimus GPU Switcher allows you to change the GPU mode easily, plus its icon is dynamic and serves as an indicator of the current mode.

💡 Tips

Black screen on Debian with Nvidia mode?

Try adding xrandr --auto to your ~/.xsessionrc. See #173 (comment), also check the Wiki for an alternative solution if this didn't work.

nvidia kernel module is named nvidia-current on Debian

If you're running into this situation you can use the --use-nvidia-current flag to make EnvyControl use the correct module name.

Wayland session is missing on Gnome 43+

GDM now requires NVreg_PreserveVideoMemoryAllocations kernel parameter which breaks sleep in nvidia and hybrid mode, as well as rtd3 in hybrid mode, so EnvyControl disables it, if you need a Wayland session follow the instructions below

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

The /usr/share/sddm/scripts/Xsetup file is missing on my system

If this ever happens please run sudo envycontrol --reset-sddm.

Files to remove if uninstalling envycontrol

The below files are created by envycontrol, and you may want to remove them manually if they are not removed automatically to avoid any incorrect system behaviour.

• /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

❓ Frequently Asked Questions (FAQ)

Read here

🐞 I have a problem

Open an issue and don't forget to complete all the requested fields!

☕️ Buy me a coffee

PayPal