Overview

Overview#

What is wakepy?#

Wakepy is a package with an Python API and a CLI tool for keeping a system awake. Namely:

⌛ 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. (See: keep.running)

🖥️ Keeping screen awake: For long running tasks which require also the screen on and screenlock and screensaver inhibited. (See: keep.presenting)

Supported platforms#

Wakepy may keep the following systems awake:

Platform Details
Windows Windows XP to Windows 11
Windows Server 2003 or higher
Mac OS Mac OS X 10.8 Mountain Lion (July 2012) or newer
Linux[1] Distributions using GNOME
Distributions using KDE Plasma[2]
Any other Desktop Environments which implement the Freedesktop.org ScreenSaver interface[2]

[1] The Linux support is under active development. Target is to support at least GNOME, KDE, Xfce, Cinnamon, LXQt and MATE Desktop Environments. [2] Only the presentation mode currently.

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:

🛡️ For security reasons

When you don’t want to use a technique which keeps the screen awake and disables the automatic screen lock. I.e. you only want to disable the automatic suspend.

🦸 You need a cross-platform solution

Same code works on Windows, macOS and Linux.

⚙️ 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 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.presenting mode:

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?#

Contents