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: <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-running-mode"><b><code>keep.running</code></b></a>)

🖥️ 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: <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-presenting-mode"><b><code>keep.presenting</code></b></a>)

Supported runtime environments

Wakepy may keep the following systems awake. ⌛: <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-running-mode">keep.running</a> mode, 🖥️:<a href="https://wakepy.readthedocs.io/stable/modes.html#keep-presenting-mode">keep.presenting</a> mode.

<table class="wakepy-table"> <colgroup> <col style="width: 31%;"> <col style="width: 55%;"> <col style="width: 14%;"> </colgroup> <thead> <tr> <th>Runtime environment</th> <th>Methods</th> <th>Modes</th> </tr> </thead> <tbody> <tr> <td>Windows<sup>[1]</sup></td> <td><a href="https://wakepy.readthedocs.io/stable/methods-reference.html#setthreadexecutionstate">SetThreadExecutionState </a></td> <td>⌛ 🖥️</td> </tr> <tr> <td>macOS<sup>[2]</sup></td> <td><a href="https://wakepy.readthedocs.io/stable/methods-reference.html#macos-caffeinate">caffeinate</a></td> <td>⌛ 🖥️</td> </tr> <tr> <td>Unix + <a href="https://en.wikipedia.org/wiki/GNOME">GNOME</a><sup>[3]</sup></td> <td><a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-gnome-sessionmanager">org.gnome.SessionManager</a><br> <a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-freedesktop-screensaver">org.freedesktop.ScreenSaver</a></td> <td>⌛ 🖥️<br/>🖥️</td> </tr> <tr> <td>Unix + <a href="https://en.wikipedia.org/wiki/KDE_Plasma">KDE Plasma</a><sup>[4]</sup></td> <td><a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-freedesktop-powermanagement">org.freedesktop.PowerManagement</a><br> <a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-freedesktop-screensaver">org.freedesktop.ScreenSaver</a></td> <td>⌛<br/>🖥️</td> </tr> <tr> <td>Unix + <a href="https://projects.linuxmint.com/cinnamon/">Cinnamon</a></td> <td><a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-gnome-sessionmanager">org.gnome.SessionManager</a><br> <a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-freedesktop-screensaver">org.freedesktop.ScreenSaver</a></td> <td>⌛ 🖥️<br/>🖥️</td> </tr> <tr> <td>Unix + <a href="https://en.wikipedia.org/wiki/Freedesktop.org">Freedesktop.org</a> DE<sup>[5]</sup></td> <td> <a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-freedesktop-powermanagement">org.freedesktop.PowerManagement</a><br> <a href="https://wakepy.readthedocs.io/stable/methods-reference.html#org-freedesktop-screensaver">org.freedesktop.ScreenSaver</a> </td> <td>⌛<br/>🖥️</td> </tr> </tbody> </table>

Unix above refers to any Unix-like systems which might use such DEs, e.g. Linux or FreeBSD. See also: Wakepy roadmap.

Installing

Wakepy supports CPython 3.7 to 3.15 (including the free-threaded versions) and PyPy 3.8 to 3.11, and may be installed from PyPI with

pip install wakepy

Wakepy can also be installed from conda-forge with

conda install wakepy

For more details and install options, see: Installing documentation.

[!NOTE] To get the wakepy <a href="https://wakepy.readthedocs.io/stable/cli-api.html">CLI command</a> working, you might need to restart the shell / terminal application.

Why wakepy?

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

<dl> <dt>🙅🏼‍♂️ Non-disruptive methods ✅</dt> <dd>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.</dd> <dt>🛡️ Safe to crash 💥</dt> <dd>No changing of any system settings; killing the process abruptly will not leave the keepawake on, and will not require any manual clean-up.</dd> <dt>🚨 For security reasons 🔒</dt> <dd>With <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-running-mode"><b><code>keep.running</code></b></a> mode you can disable <i>just</i> the automatic suspend and keep the automatic screen lock untouched.</dd> <dt>🌐 You need a cross-platform solution 🦸</dt> <dd>Same code works on Windows, macOS and Linux on multiple different Desktop Environments.</dd> <dt>💪 You want to have more control ⚙️</dt> <dd>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.</dd> <dt>✂️ You want to keep the amount of dependencies low 📦</dt> <dd>If you're running wakepy on Linux, <a href="https://jeepney.readthedocs.io/">jeepney</A> (a dependency free package) is required for D-Bus based methods. On Python 3.9 and earlier, <a href="https://pypi.org/project/typing-extensions/">typing-extensions</a> is needed for typing. Otherwise: wakepy has no python dependencies.</dd> <dt>⚖️ Package needs to have a permissive licence ✔️</dt> <dd>Wakepy is licenced under permissive <a href="https://github.com/wakepy/wakepy/blob/main/LICENSE.txt">MIT License</a>.</dd> </dl>

Command line interface (CLI)

To keep system from sleeping and prevent screen lock, run

wakepy

For keep.running mode (allows screen lock), add -r flag. See also: <a href="https://wakepy.readthedocs.io/stable/cli-api.html">CLI API</a>.

Basic usage within Python

In the simplest case, keeping a system running long running task with wakepy would be in python (See: <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-running-mode">keep.running</a>):

from wakepy import keep

@keep.running
def long_running_task():
    # Do something that takes a long time

If you want to also prevent screen lock and screen blank, use the <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-presenting-mode">keep.presenting</a> mode:

from wakepy import keep

@keep.presenting
def long_running_task():
    # Do something that takes a long time AND requires the display to stay on

[!NOTE] The decorator syntax was added in wakepy version 1.0.0

It's also possible to use the <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-running-mode">keep.running()</a> and <a href="https://wakepy.readthedocs.io/stable/modes.html#keep-presenting-mode">keep.presenting()</a> as context managers, like this:

from wakepy import keep

with keep.running()
    ...

[!TIP] See the User Guide and the available wakepy Modes and Methods

Where wakepy is used?

AI & Machine Learning

[aTrain](https://g

Wakepy

Install / Use

README