A feature-rich RFB/VNC server written in pure Python

PyVNCServer is an RFC 6143-compliant VNC server that captures your desktop and streams it to any VNC viewer. It supports multiple encodings, adaptive compression, WebSocket transport for browser access via noVNC, and network-aware performance tuning -- all from a single Python package.

git clone https://github.com/xulek/PyVNCServer.git
cd PyVNCServer
pip install -e .[dev]

# PowerShell
$env:PYTHONPATH = "src"
python -m pyvncserver --help

# Bash
PYTHONPATH=src python -m pyvncserver --help

pip install -e .[windows-capture]

Edit config/pyvncserver.toml -- set at least password for authentication:

[server]
host = "0.0.0.0"
port = 5900
password = "secret"

pyvncserver serve --config config/pyvncserver.toml

vncviewer localhost:5900

PyVNCServer serves WebSocket and standard VNC on the same port -- no external proxy required.

1. Enable WebSocket in config/pyvncserver.toml:

[features]
enable_websocket = true

[websocket]
allowed_origins = ["http://localhost:8000"]

2. Start the VNC server, then serve the web client:

pyvncserver serve --config config/pyvncserver.toml
python -m http.server 8000                              # separate terminal

3. Open http://localhost:8000/web/vnc_client.html in your browser.

For production wss:// transport, terminate TLS at a reverse proxy (e.g. Nginx). See WEBSOCKET.md for details and an Nginx config example.

All settings live in config/pyvncserver.toml, organized into sections:

# Start with default config
pyvncserver serve

# Start with custom config and debug logging
pyvncserver serve --config config/pyvncserver.toml --log-level DEBUG

# Run as Python module (no install required, set PYTHONPATH=src)
python -m pyvncserver serve --config config/pyvncserver.toml

Programmatic startup:

from pyvncserver import VNCServer

server = VNCServer(config_file="config/pyvncserver.toml")
server.start()

PyVNCServer/
├── src/
│   ├── pyvncserver/            # Packaged application (new code goes here)
│   │   ├── cli.py              # CLI entrypoint
│   │   ├── config.py           # TOML config loader
│   │   ├── app/server.py       # Main VNCServerV3 class
│   │   ├── rfb/                # Protocol layer (auth, encodings, messages)
│   │   ├── platform/           # OS integration (capture, cursor, input)
│   │   ├── runtime/            # Connection pool, network profiles, threading
│   │   ├── features/           # Clipboard, session recording, WebSocket
│   │   └── observability/      # Logging, metrics, Prometheus, profiling
│   └── vnc_lib/                # Internal implementation library
│       ├── protocol.py         # RFB protocol negotiation
│       ├── encodings.py        # Encoder implementations + EncoderManager
│       ├── screen_capture.py   # Screen capture with backend selection
│       ├── auth.py             # VNC/Tight authentication
│       └── ...                 # 20+ modules
├── config/pyvncserver.toml     # Default server configuration
├── tests/                      # 320+ pytest tests
├── benchmarks/                 # Performance measurement scripts
├── examples/                   # Demo scripts
├── web/                        # noVNC browser client
└── docs/                       # Architecture & protocol docs

# Full test suite
python -m pytest tests/ -v --tb=short

# Single test file
python -m pytest tests/test_encodings.py -v

# Single test
python -m pytest tests/test_vnc_server.py::TestClassName::test_method -v

# With coverage report
python -m pytest tests/ --cov=pyvncserver --cov=vnc_lib --cov-report=term-missing

python benchmarks/benchmark_encoders.py              # Encoder throughput (Raw/Zlib/Tight/ZRLE)
python benchmarks/benchmark_screen_capture.py         # Capture backend performance
python benchmarks/benchmark_screen_capture_methods.py 20  # Comparative backend benchmark
python benchmarks/benchmark_lan_latency.py 127.0.0.1 5900 20  # Network latency

To measure real capture latency at startup, set in config:

[server]
capture_probe_frames = 12
capture_probe_warn_ms = 40.0

Important: VNC authentication uses DES-based challenge-response and provides only basic protection. Traffic is not encrypted by default.

For production deployments:

• Set a strong password in config/pyvncserver.toml
• Run behind SSH tunneling, a VPN, or a TLS-terminating reverse proxy
• Restrict allowed_origins for WebSocket access
• Bind to 127.0.0.1 if only local access is needed
• Do not expose directly to untrusted networks

export DISPLAY=:0

pip install -r requirements.txt

This project is licensed under the MIT License.

_{Built with Python 3.13+ • RFC 6143 compliant • github.com/xulek/PyVNCServer}