Cross platform input simulation in Rust!
- Serialize/Deserialize
- Linux (X11) mouse
- Linux (X11) text
- Linux (Wayland) mouse (Experimental)
- Linux (Wayland) text (Experimental)
- Linux (libei) mouse (Experimental)
- Linux (libei) text (Experimental)
- MacOS mouse
- MacOS text
- Windows mouse
- Windows text
Enigo also works on *BSDs if they use X11 or Wayland. I don't have a machine to test it and there are no Github Action runners for it, so the BSD support is not explicitly listed.
let mut enigo = Enigo::new(&Settings::default()).unwrap();
enigo.move_mouse(500, 200, Abs).unwrap();
enigo.button(Button::Left, Click).unwrap();
enigo.text("Hello World! here is a lot of text ❤️").unwrap();For more, look at the (examples).
By default, enigo currently works on Windows, macOS and Linux (X11). If you want to be able to serialize and deserialize commands for enigo (example), you need to activate the serde feature.
There are multiple ways how to simulate input on Linux and not all systems support everything. Enigo can also use wayland protocols and libei to simulate input but there are currently some bugs with it. That is why they are hidden behind feature flags.
On Windows, mouse coordinates and display size use physical pixels. Enigo temporarily switches the calling thread to per-monitor DPI awareness for those queries, so you do not need to change the process DPI awareness mode.
Linux users may have to install libxdo-dev if they are using the xdo feature. For example, on Debian-based distros:
apt install libxdo-devOn Arch:
pacman -S xdotoolOn Fedora:
dnf install libX11-devel libxdo-develOn Gentoo:
emerge -a xdotoolSome platforms have security measures in place to prevent programs from entering keys or controlling the mouse. Have a look at the permissions documentation to see what you need to do to allow it.
Please have a look at our changelog to find out what you have to do, if you used a previous version.
If you encounter an issue and want to debug it, turn on log messages as described here.
rustfmt.toml enables wrap_comments, which needs the nightly toolchain.
Format with cargo +nightly fmt; the devcontainers install nightly. Plain
cargo fmt uses the stable toolchain and ignores the setting.
Warning: The tests will move the mouse, enter text, press keys and open some applications. Read the test cases before you run them so you know what to expect. It's best to close everything so that the tests don't mess with your system. Some of them run for a long time because they are intended to be run in the CI. Tests that share input state are serialized with serial_test, so you can run them normally:
cargo testThe browser integration test needs the serde feature, Firefox and a display.
It launches Firefox with the session's GDK_BACKEND, so it can run twice in a
Wayland session:
# Wayland: Firefox on Wayland and the backend talks to the compositor directly
cargo test --no-default-features --features wayland,serde --test integration_browser_events
cargo test --no-default-features --features xdg_desktop,smol,platform_specific,serde --test integration_browser_events
# X11: Firefox on X11 and x11rb against the X server. In a Wayland session
# DISPLAY is the compositor's Xwayland; GDK_BACKEND selects it.
GDK_BACKEND=x11 cargo test --features serde --test integration_browser_eventsThe devcontainers compile one backend per session because backend selection is
still compile-time; see KNOWN_ISSUES.md for the runtime-selection goal.
| Session | Run |
|---|---|
| Xvfb (X11, default) | cargo test (x11rb) or cargo test --no-default-features --features xdo (xdo), plus the X11 browser test |
| sway | cargo test --no-default-features --features wayland --lib, Wayland and XWayland browser tests |
| labwc | cargo test --no-default-features --features wayland --lib, Wayland and XWayland browser tests |
| GNOME Wayland (libei) | cargo test --no-default-features --features libei,tokio,platform_specific --lib, Wayland browser test |
| GNOME Wayland (xdg_desktop) | cargo test --no-default-features --features xdg_desktop,tokio,platform_specific --lib, Wayland browser test |
| GNOME Wayland (Xwayland, x11rb) | cargo test --no-default-features --features x11rb --lib and the XWayland browser test |
| GNOME X11 (Xorg) | cargo test --no-default-features --features x11rb --lib and the X11 browser test |
| Plasma Wayland (Xwayland, x11rb) | cargo test --no-default-features --features x11rb --lib and the XWayland browser test |
| Plasma X11 (Xorg) | cargo test --no-default-features --features x11rb --lib and the X11 browser test |
The containers run the tests as an unprivileged enigo user. The GNOME
Wayland container seeds a portal restore token so the first connection does not
wait for a permission dialog.
The devcontainers are development tools, not a sandbox. Opening one from an
untrusted branch builds that branch's Containerfile and runs its session
scripts; the workspace is bind-mounted, and the enigo user has passwordless
sudo inside the container (the sessions need it to start the system D-Bus).
Review .devcontainer changes like any other code and only open the
devcontainers for branches you trust.
Set ENIGO_RESTORE_TOKEN or ENIGO_RESTORE_TOKEN_FILE to reuse a portal restore
token in the examples; the examples also accept --restore-token <token>.
