{"id":10341,"library":"vncdotool","title":"VNC Do Tool (vncdotool)","description":"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.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/sibson/vncdotool","tags":["vnc","remote-control","automation","client","testing","devops","system-administration"],"install":[{"cmd":"pip install vncdotool","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Image processing and screen capture.","package":"Pillow","optional":false},{"reason":"VNC DES authentication (replaces internal implementation).","package":"pycryptodomex","optional":false}],"imports":[{"note":"The primary API client is within the 'api' submodule, not directly under 'vncdotool'.","wrong":"from vncdotool import VNCClient","symbol":"VNCClient","correct":"from vncdotool.api import VNCClient"}],"quickstart":{"code":"import os\nfrom vncdotool.api import VNCClient\n\n# Example: Connect to a VNC server, capture screen, type text, and disconnect\n\nhost = os.environ.get('VNC_HOST', 'localhost')\nport = int(os.environ.get('VNC_PORT', '5900'))\npassword = os.environ.get('VNC_PASSWORD', '')\n\ntry:\n    client = VNCClient(host=host, port=port, password=password)\n    print(f\"Successfully connected to VNC server at {host}:{port}\")\n\n    # Capture a screenshot\n    screenshot_path = 'screenshot.png'\n    client.captureScreen(screenshot_path)\n    print(f\"Screenshot saved to {screenshot_path}\")\n\n    # Type some text\n    client.keyPress('f12') # Example: Press F12\n    client.type('Hello, VNC World!')\n\n    # Wait for a brief moment\n    client.pause(1000) # Pause for 1 second (1000ms)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    if 'client' in locals() and client.connected:\n        client.disconnect()\n        print(\"Disconnected from VNC server.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.2.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.9.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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`).","cause":"The `vncdotool` package has not been installed in the active Python environment or the environment is not correctly activated.","error":"No module named 'vncdotool'"},{"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.","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.","error":"Authentication failed"},{"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.","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.","error":"Connection refused"},{"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).","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`.","error":"TypeError: fromstring() data should be bytes, not str"}]}