Skip to main content

freerdp-tk

A small launcher window for the FreeRDP remote desktop clients. It runs on Linux, Windows and macOS and needs nothing beyond Python and its built-in Tkinter.

freerdp-tk: saved connections on the left, connection settings on the right, the generated command line, and the log of a running session

  • Saved connections: a list you can filter. Double-click one to connect, or select several and connect them all at once.
  • Picks a client for you: it finds the FreeRDP clients on your PATH and in local build trees. "(auto)" prefers the SDL client, then X11, Wayland and Windows.
  • Form instead of flags: display, graphics codec (including AV1), clipboard, sound, microphone, drive sharing, log level, plus a box for extra arguments.
  • Live command preview: shows the exact command line, with the password hidden, and copies it for you.
  • Session log: runs several sessions at once and shows each client's output.

Install

uv tool install freerdp-tk   # or: pipx install freerdp-tk
freerdp-tk

You also need a FreeRDP client, for example:

Platform Client
Debian / Ubuntu sudo apt install freerdp3-sdl (or freerdp3-x11)
Fedora sudo dnf install freerdp
macOS brew install freerdp
Windows a FreeRDP build containing sdl-freerdp.exe or wfreerdp.exe, on your PATH

On Linux, a system Python may need its Tk package (sudo apt install python3-tk). The Pythons that uv installs already include Tk.

Passwords

  • Passwords are never written to disk. They are asked for once and kept in memory until the window closes.
  • With FreeRDP 3, all arguments are passed to the client through standard input (/args-from:stdin). The password therefore never appears in the process list (ps, Task Manager).
  • FreeRDP 2 has no such option, so the password goes on the command line, and the log warns you about it.

Before and after commands (SSH tunnels and more)

The Before / after tab runs your own commands around a session:

  • Before connecting: runs to the end before the client starts; if it fails, the client does not start. Tick Keep it running during the session for a command that stays up beside the session, such as a tunnel. Then wait until host:port holds the client back until that port answers.
  • Stop it when the session ends: ends the before command and everything it started, also if freerdp-tk itself crashes or is killed:
    • Linux: a small supervisor runs the command as a child subreaper, so even daemons that fork twice and leave the process group stay under it. Each is sent SIGTERM, then SIGKILL after 3 seconds.
    • Windows: the command runs in a job object that the system closes, and with it everything inside, when freerdp-tk lets go of it.
    • macOS: the same supervisor, but macOS has no subreaper: a daemon that forks twice and leaves the process group survives.
  • After disconnecting: runs once the session is over, however it ended.
  • Client proxy: passed to the client as /proxy:.

Placeholders work in all of these and in the extra arguments: %h host, %p port, %u user, %L a free local port picked for this session, %% a percent sign.

Fill in: SSH tunnel… sets it all up for the common case. It asks for a jump host and fills in:

before:      ssh -N -D 127.0.0.1:%L -o ExitOnForwardFailure=yes -o BatchMode=yes me@bastion
wait until:  127.0.0.1:%L
proxy:       socks5://127.0.0.1:%L

The RDP server then only has to be reachable from the jump host, and the client still connects by its real name, so the certificate check is unchanged. ssh runs without a terminal, so it must log in with a key or an agent, and it must already know the jump host's key (connect once with ssh in a terminal).

Where things are kept

What Where
Saved connections ~/.config/freerdp-tk/profiles.json (Linux), ~/Library/Application Support/freerdp-tk/ (macOS), %APPDATA%\freerdp-tk\ (Windows)
Extra FreeRDP source trees to search for built clients FREERDP_TK_TREES, separated like PATH. ~/projects/FreeRDP is always searched.

Limitation

The client runs without a terminal, so it cannot ask questions while connecting, such as whether to trust a new certificate. Pick a certificate policy (tofu, ignore or deny) on the Connection tab instead. The default, tofu, trusts a server's certificate the first time you connect.

Development

uv run --with-editable . python -m freerdp_tk   # run from the checkout
uv build                                         # build the sdist and wheel into dist/

The screenshot above is rendered from demo data in a virtual X server, so no real hosts end up in it. Regenerate it after changing the UI:

xvfb-run -s "-screen 0 1400x1000x24" \
    uv run --with pillow --with-editable . python scripts/screenshot.py docs/screenshot.png

Releasing to PyPI

Releases are published by GitHub Actions through trusted publishing, so no API token is needed. The version is taken from the git tag.

One-time setup:

  1. On PyPI, open Your projects → Publishing → Add a new pending publisher and enter: project freerdp-tk, owner congzhangzh, repository freerdp-tk, workflow release.yml, environment pypi.
  2. On GitHub, create an environment named pypi (Settings → Environments).

Each release after that:

git tag 0.2.0          # the version, no prefix
git push origin 0.2.0

The workflow builds the package, checks that it installs on Linux, Windows and macOS, and then uploads it to PyPI.

License

Apache-2.0, the same license as FreeRDP.

Metadata

Release files for freerdp-tk 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for freerdp-tk 0.2.0
File Size Uploaded Provenance Actions
freerdp_tk-0.2.0.tar.gz 55.0 kB With provenance Details for freerdp_tk-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for freerdp-tk 0.2.0
File Interpreter ABI Platform Actions
freerdp_tk-0.2.0-py3-none-any.whl Python 3 none any Details for freerdp_tk-0.2.0-py3-none-any.whl

Total release size: 77.5 kB

Release files / freerdp_tk-0.2.0.tar.gz

Download URL freerdp_tk-0.2.0.tar.gz
Size 55.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ac5895dc1a0416ea798e7733277ec770c0a61b54ad28e828570723aabaa541fb
BLAKE2b-256 checksum
How to use checksums
908d4f5f12a3401c6e47000f099808d00dad2227357e151ce057c6f6b01f27ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / freerdp_tk-0.2.0-py3-none-any.whl

Download URL freerdp_tk-0.2.0-py3-none-any.whl
Size 22.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3c30f691ddb29b8fd1bfd94051461cac0642df58f64b57a7204116125a88ab27
BLAKE2b-256 checksum
How to use checksums
f7012bcc73f18f04da87505c559ebe168ba69d89b14af9e210b42fbb07e5006e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for freerdp-tk 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for freerdp_tk-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page