{"id":13493173,"url":"https://github.com/bayasdev/envycontrol","last_synced_at":"2025-03-28T11:31:52.519Z","repository":{"id":37414390,"uuid":"424458609","full_name":"bayasdev/envycontrol","owner":"bayasdev","description":"Easy GPU switching for Nvidia Optimus laptops under Linux","archived":false,"fork":false,"pushed_at":"2024-10-12T13:12:33.000Z","size":199,"stargazers_count":1294,"open_issues_count":59,"forks_count":61,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-10-31T07:34:14.186Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bayasdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-04T03:20:12.000Z","updated_at":"2024-10-29T00:09:10.000Z","dependencies_parsed_at":"2024-03-06T15:42:56.851Z","dependency_job_id":"08c04149-41e7-4cce-ad56-9fb848bfa7ea","html_url":"https://github.com/bayasdev/envycontrol","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bayasdev%2Fenvycontrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bayasdev%2Fenvycontrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bayasdev%2Fenvycontrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bayasdev%2Fenvycontrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bayasdev","download_url":"https://codeload.github.com/bayasdev/envycontrol/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246021041,"owners_count":20710871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T19:01:12.885Z","updated_at":"2025-03-28T11:31:52.222Z","avatar_url":"https://github.com/bayasdev.png","language":"Python","funding_links":["https://www.paypal.com/paypalme/bayasdev"],"categories":["Python","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/bayasdev/envycontrol/raw/main/logos/dark.png\"\u003e\n  \u003cimg alt=\"EnvyControl Logo\" src=\"https://github.com/bayasdev/envycontrol/raw/main/logos/light.png\" height=\"100px\"\u003e\n\u003c/picture\u003e\n\u003cbr\u003e\nOptimus made easy\n\u003c/div\u003e\n\u003cbr\u003e\n\n# 👁‍🗨 EnvyControl\n\nEnvyControl 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.\n\n### 📖 License\n\nEnvyControl is free and open-source software released under the [MIT](https://github.com/bayasdev/envycontrol/blob/main/LICENSE) license.\n\n### ⚠️ Disclaimer\n\n**This software is provided 'as-is' without any express or implied warranty.**\n\nKeep in mind any custom X.org configuration may get deleted or overwritten when switching modes.\n\n## ✨ Features\n\n- 🐍 Written in Python 3+ for portability and compatibility\n- 🐧 Works across all major Linux distros ([tested distros](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#tested-distros))\n- 🖥️ 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)\n- 🔋 Save battery with integrated graphics mode\n- 💻 PCI-Express Runtime D3 (RTD3) Power Management support for Turing and later\n- 🎮 Coolbits support for GPU overclocking\n- 🔥 Fix screen tearing with ForceCompositionPipeline\n\n## 📖 Graphics modes\n\n### Integrated\n\n- The integrated Intel or AMD iGPU is used exclusively\n- Nvidia dGPU is turned off to reduce power consumption\n- External screens cannot be used if the video ports are wired to the dGPU\n\n### Hybrid\n\n- Enables PRIME render offloading\n- RTD3 allows the dGPU to be dynamically turned off when not in use\n  - 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))\n    - `0` disabled\n    - `1` coarse-grained\n    - `2` fine-grained (default value if you don't provide one)\n    - `3` fine-grained for Ampere and later\n  - Only works in Turing and later\n- Performance on external screens might be reduced\n\n### Nvidia\n\n- The Nvidia dGPU is used exclusively\n- Higher graphical performance and higher power consumption\n- Recommended when working with external screens\n  - If facing screen tearing enable ForceCompositionPipeline with the `--force-comp` flag\n- Allows overlocking (not recommended) with the `--coolbits` flag\n  - 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)\n- Wayland sessions default to hybrid mode\n\n## ⚡️ Usage\n\n```\nusage: envycontrol.py [-h] [-v] [-q] [-s MODE] [--dm DISPLAY_MANAGER] [--force-comp] [--coolbits [VALUE]] [--rtd3 [VALUE]] [--reset-sddm] [--reset] [--verbose]\n\noptions:\n  -h, --help            show this help message and exit\n  -v, --version         Output the current version\n  -q, --query           Query the current graphics mode\n  -s MODE, --switch MODE\n                        Switch the graphics mode. Available choices: integrated, hybrid, nvidia\n  --dm DISPLAY_MANAGER  Manually specify your Display Manager for Nvidia mode. Available choices: gdm, gdm3, sddm, lightdm\n  --force-comp          Enable ForceCompositionPipeline on Nvidia mode\n  --coolbits [VALUE]    Enable Coolbits on Nvidia mode. Default if specified: 28\n  --rtd3 [VALUE]        Setup PCI-Express Runtime D3 (RTD3) Power Management on Hybrid mode. Available choices: 0, 1, 2, 3. Default if specified: 2\n  --use-nvidia-current  Use nvidia-current instead of nvidia for kernel modules\n  --reset-sddm          Restore default Xsetup file\n  --reset               Revert changes made by EnvyControl\n  --cache-create        Create cache used by EnvyControl; only works in hybrid mode\n  --cache-delete        Delete cache created by EnvyControl\n  --cache-query         Show cache created by EnvyControl\n  --verbose             Enable verbose mode\n```\n\n### Some examples\n\nSet graphics mode to integrated:\n\n```\nsudo envycontrol -s integrated\n```\n\nSet graphics mode to hybrid and enable fine-grained power control:\n\n```\nsudo envycontrol -s hybrid --rtd3\n```\n\nSet graphics mode to nvidia, enable ForceCompositionPipeline and Coolbits with a value of 24:\n\n```\nsudo envycontrol -s nvidia --force-comp --coolbits 24\n```\n\nSet current graphics mode to nvidia and specify to setup LightDM display manager\n\n```\nsudo envycontrol -s nvidia --dm lightdm\n```\n\nQuery the current graphics mode:\n\n```\nenvycontrol --query\n```\n\nRevert all changes made by EnvyControl:\n\n```\nsudo envycontrol --reset\n```\n\n### Caching added with 3.4.0\nA 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.\n\n#### Cache file location\n\nNote 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.\n\n```python\nCACHE_FILE_PATH = '/var/cache/envycontrol/cache.json'\n```\n\n#### File format\n\n```json\n{\n  \"nvidia_gpu_pci_bus\": \"PCI:1:0:0\"\n}\n```\n\nThe cache is automatically re-created whenever a switch from hybrid mode is performed.\n\n#### Caching command line examples\n\nCreate cache used by EnvyControl; only works in hybrid mode\n\n```\nsudo envycontrol --cache-create\n```\n\nWhen create cache is called when the system is in integrated or nvidia modes\n\n```\nsudo envycontrol --cache-create\n...\nValueError: --cache-create requires that the system be in the hybrid Optimus mode\n```\n\n\nDelete cache created by EnvyControl\n\n```\nsudo envycontrol --cache-delete\n```\n\nShow cache created by EnvyControl\n\n```\nsudo envycontrol --cache-query\n```\n\n\n## ⬇️ Getting EnvyControl\n\n### Arch Linux ([AUR](https://aur.archlinux.org/packages/envycontrol))\n\n1. `yay -S envycontrol`\n2. Run `sudo envycontrol -s \u003cMODE\u003e` to switch graphics modes\n\n### Fedora\n\nUse the [COPR](https://copr.fedorainfracloud.org/coprs/sunwire/envycontrol/) maintained by [@sunwire](https://github.com/sunwire)\n\n1. Enable the repository with `sudo dnf copr enable sunwire/envycontrol`\n2. `sudo dnf install python3-envycontrol`\n3. Run `sudo envycontrol -s \u003cMODE\u003e` to switch graphics modes\n\n### Enterprise Linux + EPEL 9 (RHEL 9, Rocky Linux 9, CentOS Stream 9, Alma Linux 9 etc.)\n\nUse the [COPR](https://copr.fedorainfracloud.org/coprs/thonkdifferent/envycontrol/) maintained by [@thonkdifferent](https://github.com/thonkdifferent)\n\n1. Enable the repository with `sudo dnf copr enable thonkdifferent/envycontrol`\n2. `sudo dnf install python3-envycontrol`\n3. Run `sudo envycontrol -s \u003cMODE\u003e` to switch graphics modes\n\n### Ubuntu / Debian\n\nSince [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:\n\n1. Go to the [latest release page](https://github.com/bayasdev/envycontrol/releases/latest)\n2. Download the attached `python3-envycontrol_version.deb` package\n3. Install it with `sudo apt -y install ./python3-envycontrol_version.deb`\n4. Run `sudo envycontrol -s \u003cMODE\u003e` to switch graphics modes\n\n### Nixos\n\nIf you're using Nix Flakes:\n\n- Script could be executed using this command:\n\n```sh\nnix run github:bayasdev/envycontrol -- \u003cargs\u003e\n```\n\n- For system-wide installation, add this flake to inputs in your configuration:\n\n```sh\ninputs = {\n  # ...\n  envycontrol.url = github:bayasdev/envycontrol\n};\n```\n\nAnd mention it in the packages like this:\n\n```sh\nenvycontrol.packages.x86_64-linux.default\n```\n\nThanks to [@ITesserakt](https://github.com/ITesserakt) for adding initial NixOS support!\n\n### OSTree Distros (Silverblue, Kinoite, Bazzite, etc.)\n\nThese 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).\n\n1. Enable the COPR by downloading the `.repo` file from the COPR page, linked above. Put the `.repo` file in `/etc/yum.repos.d`.\n2. Clean package cache with `rpm-ostree cleanup -m`.\n3. Overlay the package with `rpm-ostree install python-envycontrol`.\n4. Reboot to apply the overlay.\n5. Use EnvyControl with `sudo envycontrol -s \u003cMODE\u003e`\n\n### From source\n\n1. Clone this repository with `git clone https://github.com/bayasdev/envycontrol.git` or download the latest tarball from the releases page\n2. Run the script from the root of the repository like this `python ./envycontrol.py -s \u003cMODE\u003e`\n\n💡 Replace `python` with `python3` on Ubuntu/Debian\n\n### Install globally as a pip package\n\n- From the root of the cloned repository run `sudo pip install .`\n- Now you can run `sudo envycontrol -s \u003cMODE\u003e` from any directory to switch graphics modes.\n\n## 👕 GUIs\n\n### Gnome Extension\n\nThe [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/).\n\n**Make sure to have EnvyControl installed globally!**\n\n![gpu profile selector screenshot](https://github.com/LorenzoMorelli/GPU_profile_selector/raw/main/img/extension_screenshot.png)\n\n### KDE Widget\n\n[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.\n\n![Screenshot_20230703_153738](https://github.com/enielrodriguez/optimus-gpu-switcher/assets/31964610/ace0c67e-9428-49fd-895c-48a236727898)\n\n## 💡 Tips\n\n### Black screen on Debian with Nvidia mode?\n\nTry 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.\n\n### `nvidia` kernel module is named `nvidia-current` on Debian\n\nIf you're running into this situation you can use the `--use-nvidia-current` flag to make EnvyControl use the correct module name.\n\n### Wayland session is missing on Gnome 43+\n\nGDM 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\n\n```\nsudo systemctl enable nvidia-{suspend,resume,hibernate}\nsudo ln -s /dev/null /etc/udev/rules.d/61-gdm.rules\n```\n\n### The `/usr/share/sddm/scripts/Xsetup` file is missing on my system\n\nIf this ever happens please run `sudo envycontrol --reset-sddm`.\n\n### Files to remove if uninstalling `envycontrol`\nThe 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.\n* `/var/cache/envycontrol`\n* `/etc/modprobe.d/blacklist-nvidia.conf`\n* `/lib/udev/rules.d/50-remove-nvidia.rules`\n* `/lib/udev/rules.d/80-nvidia-pm.rules`\n* `/etc/X11/xorg.conf`\n* `/etc/X11/xorg.conf.d/10-nvidia.conf`\n* `/etc/modprobe.d/nvidia.conf`\n\n## ❓ Frequently Asked Questions (FAQ)\n\n[Read here](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions)\n\n## 🐞 I have a problem\n\nOpen an issue and **don't forget to complete all the requested fields!**\n\n## ☕️ Buy me a coffee\n\n[PayPal](https://www.paypal.com/paypalme/bayasdev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbayasdev%2Fenvycontrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbayasdev%2Fenvycontrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbayasdev%2Fenvycontrol/lists"}