# envycontrol

**Repository Path**: chenxin_gitee/envycontrol

## Basic Information

- **Project Name**: envycontrol
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> [!IMPORTANT]
> **Project Status**  
> 
> Hi! I'm [Victor](https://github.com/bayasdev), 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](https://github.com/bayasdev/envycontrol/blob/main/LICENSE) 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](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#tested-distros))
- 🖥️ Supports GDM, SDDM and LightDM display managers ([manual setup instructions](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#what-to-do-if-my-display-manager-is-not-supported) 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](http://us.download.nvidia.com/XFree86/Linux-x86_64/530.30.02/README/dynamicpowermanagement.html))
    - `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](https://wiki.archlinux.org/title/NVIDIA/Tips_and_tricks#Overclocking_and_cooling)
- 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.

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

#### File format

```json
{
  "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](https://aur.archlinux.org/packages/envycontrol))

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

### Fedora

Use the [COPR](https://copr.fedorainfracloud.org/coprs/sunwire/envycontrol/) maintained by [@sunwire](https://github.com/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](https://copr.fedorainfracloud.org/coprs/thonkdifferent/envycontrol/) maintained by [@thonkdifferent](https://github.com/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](https://www.linuxuprising.com/2023/03/next-debianubuntu-releases-will-likely.html) 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](https://github.com/bayasdev/envycontrol/releases/latest)
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:

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

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

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

And mention it in the packages like this:

```sh
envycontrol.packages.x86_64-linux.default
```

Thanks to [@ITesserakt](https://github.com/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](https://copr.fedorainfracloud.org/coprs/sunwire/envycontrol/) maintained by [@sunwire](https://github.com/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](https://github.com/LorenzoMorelli/GPU_profile_selector) extension provides a simple way to switch between graphics modes in a few clicks, you can get it from [here](https://extensions.gnome.org/extension/5009/gpu-profile-selector/).

**Make sure to have EnvyControl installed globally!**

![gpu profile selector screenshot](https://github.com/LorenzoMorelli/GPU_profile_selector/raw/main/img/extension_screenshot.png)

### KDE Widget

[Optimus GPU Switcher](https://github.com/enielrodriguez/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.

![Screenshot_20230703_153738](https://github.com/enielrodriguez/optimus-gpu-switcher/assets/31964610/ace0c67e-9428-49fd-895c-48a236727898)

## 💡 Tips

### Black screen on Debian with Nvidia mode?

Try adding `xrandr --auto` to your `~/.xsessionrc`. See https://github.com/bayasdev/envycontrol/issues/173#issuecomment-2205292306, also check the [Wiki](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#what-to-do-if-my-display-manager-is-not-supported) 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](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions)

## 🐞 I have a problem

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

## ☕️ Buy me a coffee

[PayPal](https://www.paypal.com/paypalme/bayasdev)