Overview

Overview#

What is wakepy?#

Wakepy is a package with an Python API and a CLI tool for keeping a system awake. It has two main modes:

⌛ Keeping CPU awake: For long running tasks. Inhibit the automatic, timer based sleep or suspend action, but allow screenlock and screensaver turning on and monitor turning off. E.g. for training machine learning models, video encoding and web scraping. (See: keep.running)

🖥️ Keeping screen awake: For long running tasks which require also the screen on and screenlock and screensaver inhibited. E.g. for showing a video and dashboard / monitoring apps. (See: keep.presenting)

Supported platforms#

Wakepy may keep the following systems awake. ⌛: keep.running mode, 🖥️:keep.presenting mode.

Platform Methods Modes
Windows[1] SetThreadExecutionState ⌛ 🖥️
macOS[2] caffeinate ⌛ 🖥️
GNOME[3] org.gnome.SessionManager
org.freedesktop.ScreenSaver		 ⌛ 🖥️
KDE Plasma[4] org.freedesktop.PowerManagement
org.freedesktop.ScreenSaver		 ⌛ 🖥️
Freedesktop.org[5] org.freedesktop.PowerManagement
org.freedesktop.ScreenSaver 		⌛ 🖥️

Installing#

Wakepy supports CPython 3.7 to 3.13, and may be installed with

pip install wakepy

To get the wakepy CLI command working, you might need to restart the shell / terminal application.

Why wakepy?#

Here’s some reasons why you might want to consider using wakepy:

🙅🏼‍♂️ Non-disruptive methods ✅
No mouse wiggling or pressing random keys like F15. Wakepy is completely non-disruptive. It uses the APIs and programs the system provides for keeping a system awake.
🛡️Safe to crash 💥
No changing of any system settings; killing the process abruptly will not leave the keepawake on, and will not require any manual clean-up.
🚨 For security reasons 🔒
With keep.running mode you can disable just the automatic suspend and keep the automatic screen lock untouched.
🌐 You need a cross-platform solution 🦸
Same code works on Windows, macOS and Linux on multiple different Desktop Environments.
💪 You want to have more control ⚙️
It is possible to whitelist or blacklist the used wakepy Methods. It is also possible to prioritize them and define a on-fail action in case activating a wakepy mode fails.
✂️ You want to keep the amount of dependencies low 📦
If you're running wakepy on Linux, jeepney (a dependecy free package) is required for D-Bus based methods. On Python 3.7, typing-extensions is needed for typing. Otherwise: wakepy has no python dependencies.
⚖️ Package needs to have a permissive licence ✔️
Wakepy is licenced under permissive MIT License.

Command line interface (CLI)#

To keep system from sleeping, run

wakepy

For presentation mode, add -p flag. See also: CLI API.

Basic usage within Python#

In the simplest case, keeping a system running long running task with wakepy would be in python (See: keep.running):

from wakepy import keep

with keep.running():
    # Do something that takes a long time. The system may start screensaver
    # / screenlock or blank the screen, but CPU will keep running.

If you want to also prevent screen lock and screen blank, use the keep.presentingmode:

from wakepy import keep

with keep.presenting():
    # Do something that takes a long time and requires the screen to be awake

Next Steps

See the User Guide and the available wakepy Modes and Methods

Wakepy API is still experimental 🚧

Since wakepy is still 0.x.x, the API might change without further notice from one release to another. After that, breaking changes should occur only part of a major release (e.g. 1.x.x -> 2.0.0).

Where wakepy is used?#

Footnotes#

[1] Windows XP or higher. Windows Server 2003 or higher.

[2] Mac OS X 10.8 Mountain Lion (July 2012) or newer.

[3] GNOME 2.24 (Sept 2008) onwards.

[4] KDE Plasma 5.12.90 (May 2018) onwards.

[5] Freedesktop.org compliant Desktop Environments on Unix-line (Linux/BSD) system which implements the listed D-Bus interfaces.
Contents