vncdotool is a command line VNC client. It can be useful to automating interactions with virtual machines or hardware devices that are otherwise difficult to control.
It's under active development and seems to be working, but please report any problems you have.
To use vncdotool you need a VNC server. Most virtualization products include one, or use RealVNC, TightVNC, or clone your Desktop using x11vnc.
Once, you have a server running you can install vncdotool from pypi:
pip install vncdotool
and then send a message to the vncserver with:
vncdo -s vncserver type "hello world"
The vncserver argument needs to be in the format address[:display|::port]. For example:
# connect to 192.168.1.1 on default port 5900
vncdo -s 192.168.1.1 type "hello world"
# connect to localhost on display :3 (port 5903)
vncdo -s localhost:3 type "hello world"
# connect to myvncserver.com on port 5902 (two colons needed)
vncdo -s myvncserver.com::5902 type "hello world"
# connect via IPv6 to localhost on display :3 (port 5903)
vncdo -s '[::1]:3' type "hello IPv6"
# ^ ^ mind those square brackets around the IPv6 address
You can also take a screen capture with:
vncdo -s vncserver capture screen.png
More documentation can be found on Read the Docs.
vncdotool speaks standard RFB and works with far more servers than we test. This says what we have evidence for, not what works.
Supported — all basic function known to work, regression tested on every pull request: TigerVNC, x11vnc, wayvnc, LibVNCServer, QEMU's built-in server, Selenoid.
Supported on their own OS — the same journey, but only on the pull requests that touch code able to affect it, since these servers need a Windows or macOS runner: UltraVNC on Windows, and Apple Screen Sharing on macOS for connect, auth and input. Screen Sharing's rendering is checked by hand rather than in CI: a hosted macOS runner has no attached display, so its captures come back near-solid whatever the client does.
Compatible — a user reported it working, or we ran the compatibility suite against it once. Not tracked by CI, so it ages. Nothing listed yet.
Broken — we tried it and it does not work:
KasmVNC. Connecting, key input and capture
work; any pointer event stops the server answering, and it drops the
connection twenty seconds later. KasmVNC states that it has left the RFB
specification and does not support VNC client applications, so expect no
fix. vncdo --dialect kasmvnc sends the eleven-byte pointer event its
server reads instead of RFB's six, which keeps the session alive and moves
the pointer; a button press reaches the X server, but has not been seen to
reach an application.
TBD — no data gathered: RealVNC, TightVNC, TurboVNC, PiKVM, and everything else. It should work; we make no claim. A report either way is welcome, and is how a server moves up.
How the servers are tested is in specs/testing-framework.md; the fleet
itself is tests/servers/docker-compose.yml.
If you need help getting VNCDoTool working try the community at Stackoverflow.
Patches, and ideas for improvements are welcome and appreciated, via GitHub issues. If you are reporting a bug or issue please include the version of both vncdotool and the VNC server you are using it with.
Thanks to Chris Liechti, techtonik and Todd Whiteman for developing the RFB and DES implementations used by vncdotool. Also, to the TigerVNC project for creating a community focus RFB specification document
