VNC Do Tool (vncdotool)

1.3.0 · active · verified Fri Apr 17

vncdotool is a command-line VNC client that also provides a Python API for programmatic interaction with VNC servers. It enables automation of VNC sessions, including screen capture, sending keystrokes, and executing commands, making it useful for testing, system administration, and CI/CD pipelines. The library is currently at version 1.3.0 and has an active but irregular release cadence.

Common errors

```
No module named 'vncdotool'
```
cause The `vncdotool` package has not been installed in the active Python environment or the environment is not correctly activated.

fix Ensure your virtual environment is active and run `pip install vncdotool`. If using a specific Python version, ensure `pip` corresponds to that version (e.g., `python3 -m pip install vncdotool`).
```
Authentication failed
```
cause The VNC server rejected the provided password. This can be due to an incorrect password, a misconfigured VNC server, or the server expecting a different authentication scheme.

fix Double-check the VNC password. Verify the VNC server's logs for authentication failures. Ensure the server supports standard VNC password authentication. Some VNC servers may require `vncdotool` to pass specific options like `--password-required` if using the command line.
```
Connection refused
```
cause The `vncdotool` client could not establish a connection with the VNC server. This typically indicates the VNC server is not running, is running on a different port, is listening on a different IP address, or a firewall is blocking the connection.

fix Verify the VNC server is running and listening on the specified host and port (default 5900). Check firewall rules on both the client and server machines. Confirm the IP address and port are correct.
```
TypeError: fromstring() data should be bytes, not str
```
cause This error often occurs in Python 3 code that relies on legacy `PIL` (Python Imaging Library) behavior, specifically when handling image data. `vncdotool` itself moved to `Pillow` and uses `frombytes`.

fix Ensure any custom image processing code that interacts with `vncdotool` output is compatible with Python 3 and `Pillow`. Specifically, use `Image.frombytes()` instead of `Image.fromstring()` for byte data. (Note: `vncdotool` versions 0.10.0 and newer address this internally).

Warnings

breaking Python 2.x support was dropped in version 1.1.0. Attempting to use vncdotool 1.1.0 or newer with Python 2 will result in `SyntaxError` or `ImportError`.
Fix: Upgrade your Python environment to Python 3 (3.6+ is recommended for modern features and type hinting). Reinstall vncdotool in the Python 3 environment.
gotcha Older versions of `vncdotool` (prior to 1.2.0) had issues with `api.shutdown()` and `api.disconnect()` potentially raising exceptions or failing silently. This could lead to unhandled errors or zombie connections.
Fix: Upgrade to vncdotool version 1.2.0 or later to benefit from the fixes related to these API calls. Always ensure proper `try...finally` blocks for connection management.
gotcha `vncdotool` replaced `PIL` (Python Imaging Library) with `Pillow` as its imaging dependency in version 0.9.0. Codebases explicitly depending on `PIL` might encounter import errors or deprecated functionality.
Fix: Ensure your project uses `Pillow` for image manipulation and avoids direct `PIL` imports. If you were manipulating images returned by `vncdotool`, ensure your code is compatible with `Pillow`'s API.
gotcha The default behavior introduced in version 0.9.0 is to pause for 10ms between commands. While this improves compatibility with some VNC servers, it might slightly slow down scripts expecting immediate command execution.
Fix: If your script requires faster command execution or you experience unexpected delays, you can explicitly set the pause duration using `client.pause(milliseconds)` or `client.setTimeout(milliseconds)` methods within the API.

Install

pip install vncdotool Install stable version

Imports

VNCClient
wrong:
```
from vncdotool import VNCClient
```
correct:
```
from vncdotool.api import VNCClient
```
The primary API client is within the 'api' submodule, not directly under 'vncdotool'.

Quickstart

This quickstart demonstrates how to connect to a VNC server using the `VNCClient` API, capture a screenshot, type some text, and then disconnect. It uses environment variables for host, port, and password for secure credential handling, falling back to common defaults.

import os
from vncdotool.api import VNCClient

# Example: Connect to a VNC server, capture screen, type text, and disconnect

host = os.environ.get('VNC_HOST', 'localhost')
port = int(os.environ.get('VNC_PORT', '5900'))
password = os.environ.get('VNC_PASSWORD', '')

try:
    client = VNCClient(host=host, port=port, password=password)
    print(f"Successfully connected to VNC server at {host}:{port}")

    # Capture a screenshot
    screenshot_path = 'screenshot.png'
    client.captureScreen(screenshot_path)
    print(f"Screenshot saved to {screenshot_path}")

    # Type some text
    client.keyPress('f12') # Example: Press F12
    client.type('Hello, VNC World!')

    # Wait for a brief moment
    client.pause(1000) # Pause for 1 second (1000ms)

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if 'client' in locals() and client.connected:
        client.disconnect()
        print("Disconnected from VNC server.")

view raw JSON →