Installation

This guide covers the installation process for WindMouse and its optional dependencies.

Requirements

Python 3.10 or higher
NumPy 1.20 or higher (automatically installed)

Operating System Support:

PyAutoGUI backend: Windows, macOS, Linux
AutoHotkey backend: Windows only

Standard Installation

The basic installation includes the core WindMouse algorithm and NumPy dependency:

pip install windmouse

This installs the core library without any controller backends.

Modern Alternative (uv)

uv is a modern, fast Python package installer:

uv add windmouse

Installing Backend Dependencies

WindMouse supports multiple backends for controlling the mouse. Choose the one that fits your needs.

PyAutoGUI Backend (Recommended)

PyAutoGUI is a cross-platform library that works on Windows, macOS, and Linux:

pip install windmouse[pyautogui]

Or with uv:

uv add "windmouse[pyautogui]"

Additional PyAutoGUI Requirements:

On Linux, you may need to install additional dependencies:

# Ubuntu/Debian
sudo apt-get install python3-tk python3-dev

# Fedora
sudo dnf install python3-tkinter python3-devel

# Arch Linux
sudo pacman -S tk

On macOS, PyAutoGUI should work out of the box on most systems.

AutoHotkey Backend (Windows Only)

AutoHotkey provides native Windows integration and potentially smoother mouse movements:

pip install windmouse[ahk]

Or with uv:

uv add "windmouse[ahk]"

Important: You must have AutoHotkey installed on your system:

Download AutoHotkey from https://www.autohotkey.com/
Install it (the default installation is sufficient)
Ensure it’s accessible from your system PATH

Install All Backends

To install both backends at once:

pip install windmouse[all]

Or with uv:

uv add "windmouse[all]"

Development Installation

If you want to contribute to WindMouse or run the examples, clone the repository and install in development mode:

git clone https://github.com/AsfhtgkDavid/windmouse.git
cd windmouse
pip install -e .[all,dev]

Or with uv:

git clone https://github.com/AsfhtgkDavid/windmouse.git
cd windmouse
uv sync --all-groups

Verifying Installation

After installation, verify that WindMouse is working:

# Test with PyAutoGUI
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController()
print("PyAutoGUI backend loaded successfully!")

For AutoHotkey (Windows only):

# Test with AHK
from ahk import AHK
from windmouse.ahk_controller import AHKMouseController

ahk = AHK()
mouse = AHKMouseController(ahk)
print("AHK backend loaded successfully!")

Troubleshooting

Import Errors

Problem: ImportError: You need install windmouse[pyautogui]

Solution: Install the appropriate backend extras:

pip install windmouse[pyautogui]

Problem: OSError: Ahk available only for Windows

Solution: The AutoHotkey backend only works on Windows. Use PyAutoGUI on other platforms.

Permission Errors (Linux)

Problem: Mouse doesn’t move or permission denied errors on Linux.

Solution: On some Linux systems, you may need to run your script with appropriate permissions or configure X11 access:

# Option 1: Run with sudo (not recommended for production)
sudo python your_script.py

# Option 2: Configure X11 to allow connections (better approach)
xhost +local:

# Option 3: Use accessibility features (distro-specific)
# Check your distribution's documentation for enabling accessibility

PyAutoGUI Issues on macOS

Problem: PyAutoGUI not working on macOS.

Solution: You may need to grant accessibility permissions:

Go to System Preferences → Security & Privacy → Privacy → Accessibility
Add your terminal application or Python interpreter to the list
Check the box to grant permission
Restart your terminal/IDE

AutoHotkey Not Found (Windows)

Problem: AutoHotkey is not installed or not in PATH

Solution:

Download and install AutoHotkey from https://www.autohotkey.com/
Ensure the installation directory is in your system PATH
Restart your terminal/IDE after installation
Verify by running ahk in Command Prompt

Virtual Display (Headless Servers)

Problem: Need to run WindMouse on a headless server (no display).

Solution: Use a virtual display driver like Xvfb on Linux:

# Install Xvfb
sudo apt-get install xvfb

# Run your script with virtual display
xvfb-run python your_script.py

For Windows servers, consider using virtual desktop tools or remote desktop services.

NumPy Compatibility

Problem: NumPy version conflicts or import errors.

Solution: WindMouse requires NumPy >= 1.20. Update NumPy:

pip install --upgrade numpy

Type Checking Issues

Problem: mypy reports errors in WindMouse code.

Solution: Install type stubs for dependencies:

pip install types-pyautogui

Next Steps

Once installation is complete, head to the Usage Guide guide to learn how to use WindMouse in your projects.