![EnvyControl Logo](https://github.com/bayasdev/envycontrol/raw/main/logos/light.png)
Optimus made easy
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.
EnvyControl is free and open-source software released under the MIT license.
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.
- ๐ 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
- 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
- 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
disabled1
coarse-grained2
fine-grained (default value if you don't provide one)3
fine-grained for Ampere and later
- Only works in Turing and later
- Available choices for the
- Performance on external screens might be reduced
- 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
- If facing screen tearing enable ForceCompositionPipeline with the
- Allows overlocking (not recommended) with the
--coolbits
flag- The default value is
28
bits however it can be manually adjusted according to this guide
- The default value is
- Wayland sessions default to hybrid mode
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
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
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.
CACHE_FILE_PATH = '/var/cache/envycontrol/cache.json'
{
"nvidia_gpu_pci_bus": "PCI:1:0:0"
}
The cache is automatically re-created whenever a switch from hybrid mode is performed.
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
Arch Linux (AUR)
yay -S envycontrol
- Run
sudo envycontrol -s <MODE>
to switch graphics modes
Use the COPR maintained by @sunwire
- Enable the repository with
sudo dnf copr enable sunwire/envycontrol
sudo dnf install python3-envycontrol
- Run
sudo envycontrol -s <MODE>
to switch graphics modes
Since PEP668 adoption is no longer possible to install pip packages outside a virtual environment, instead use the provided deb package:
- Go to the latest release page
- Download the attached
python3-envycontrol_version.deb
package - Install it with
sudo apt -y install ./python3-envycontrol_version.deb
- Run
sudo envycontrol -s <MODE>
to switch graphics modes
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!
- Clone this repository with
git clone https://github.com/bayasdev/envycontrol.git
or download the latest tarball from the releases page - Run the script from the root of the repository like this
python ./envycontrol.py -s <MODE>
๐ก Replace python
with python3
on Ubuntu/Debian
- 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.
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!
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.
If you're running into this situation you can use the --use-nvidia-current
flag to make EnvyControl use the correct module name.
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
If this ever happens please run sudo envycontrol --reset-sddm
.
Open an issue and don't forget to complete all the requested fields!