[!IMPORTANT] Project Status

Hi! I'm Victor, the original author of EnvyControl. I built this over a weekend in 2021 because there wasn't any reliable solution to properly disable the Nvidia GPU that was draining my Acer Predator Helios 300's battery. I used it heavily back then, but I switched to macOS full-time and no longer run Linux daily, so I can't provide timely bug fixes, new features, or real support anymore.

That said, EnvyControl still works well for many people on recent distros, thanks to the many PRs I've received over the years. I'm happy to transfer ownership to an active OSS initiative focused on building tools for the greater Linux ecosystem.

Thanks for all the support over the years! ❤️

PS: If I built this today, I'd probably use Go or Rust :)

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/bayasdev/envycontrol/raw/main/logos/dark.png"> <img alt="EnvyControl Logo" src="https://github.com/bayasdev/envycontrol/raw/main/logos/light.png" height="100px"> </picture> <br> Optimus made easy </div> <br>

👁‍🗨 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)

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

Fedora

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

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

Use the COPR maintained by @thonkdifferent

Enable the repository with sudo dnf copr enable thonkdifferent/envycontrol
sudo dnf install python3-envycontrol
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:

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

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.

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

From source

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

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](https://github.c

Envycontrol

Install / Use

README