Skip to main content

freerdp-tk

A small launcher window for the FreeRDP 3 SDL client, with the client inside. It runs on Linux, Windows and macOS: uvx freerdp-tk brings everything it needs, the client, Python with Tkinter and the keyring package.

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.
  • Finds the client for you: "(auto)" takes the first FreeRDP 3 SDL client on your PATH (sdl-freerdp, sdl-freerdp3, sdl3-freerdp), then in a local build tree, then the one that came with freerdp-tk. PATH order decides, whatever the names: a release that puts its own bin/ first gets its own client, not the system's. The SDL client is the one FreeRDP actively develops, and the same on Linux, Windows and macOS. You can still pick another FreeRDP 3 program with ….
  • Form instead of flags: display, monitors (List… asks the client which ones it sees, then you tick them), 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

uvx freerdp-tk               # run it once, without installing
uv tool install freerdp-tk   # or install it: then just freerdp-tk (pipx install freerdp-tk works too)

That is all: the wheel for your platform carries the FreeRDP SDL client, one program of about 25 MB.

Platform Client in the wheel
Linux x86_64, aarch64 yes, with glibc 2.34 or newer (RHEL 9, Debian 12, Ubuntu 22.04, Fedora 35 and newer) and PulseAudio's libpulse.so.0, which every desktop has (else sudo apt install libpulse0)
macOS 12 and newer, Apple Silicon and Intel yes
Windows 10 and 11, x86_64 and ARM64 yes
Anything else (musl, an older glibc, a BSD) no: the same freerdp-tk without a client, see below

A client you installed yourself still comes first, as long as it is FreeRDP 3. To install one, or where no wheel has a client:

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

About that client: it is a portable build from rdp-release-kit, unofficial and a preview: FreeRDP's master plus open pull requests, with AV1, AV2 and Opus. client.lock pins the release and its SHA-256. It decodes H.264 through the system on macOS (VideoToolbox) and Windows (Media Foundation). On Linux it has no H.264, since it carries neither OpenH264 nor FFmpeg: leave the codec on its default, pick AV1 or progressive, or use a client of your own. freerdp_tk/client/ in the installed package holds its MANIFEST (what it was built from) and licenses/, one folder per component.

Tk: the window needs a Python with Tk. The Pythons that uv installs include it; a Linux system Python often does not (sudo apt install python3-tk, sudo dnf install python3-tkinter). uv takes the system Python when there is one, so:

  • started by uvx, freerdp-tk notices a Python without Tk and starts again with uv's own Python (it downloads one the first time); uvx --managed-python freerdp-tk goes there directly;
  • installed with uv tool install, use uv tool install --managed-python freerdp-tk on such a system;
  • anywhere else, it says what to install and exits.

On Linux, the Tk in uv's Pythons draws with the X core fonts (it is built without Xft), which often lack … and •: freerdp-tk then shows ... and * instead.

Passwords

  • Saved in the system keyring, never in a file. With Remember it in the system keyring ticked (the default), the password goes to the system's own store: Credential Manager on Windows, the Keychain on macOS, the Secret Service (GNOME Keyring, KeePassXC) or KWallet on Linux. From then on a double-click connects without asking. The connections file only keeps whether the box is ticked.
  • The password dialog has the same box: untick it, and the password stays in memory only, until the window closes. Forget removes a saved password. Deleting a connection removes its password too, unless another saved connection logs in to the same account.
  • A rejected password is asked for again. When the client exits because the server turned the password down (exit codes 132, 134, 154 and 159 of the SDL client), freerdp-tk asks for another one and connects again; with the box ticked, the new password replaces the saved one. A locked, expired or disabled account is not asked again, since another password would not help.
  • An entry is named after the account it logs in to, freerdp-tk/<domain\user>@<host>:<port>, not after the connection. Renaming a connection keeps its password, and two connections to one account share it.
  • No usable keyring (on Linux: no Secret Service or KWallet, or no D-Bus session, as over plain SSH): the box is greyed out with the reason, and passwords are asked for and kept in memory only. freerdp-tk never falls back to a file. A locked keyring is unlocked through the system's own prompt; if that fails or is cancelled, freerdp-tk asks for the password instead. The keyring is used from a thread of its own, so a slow one (an unlock prompt, a Secret Service that D-Bus takes two minutes to give up on) never freezes the window.
  • What the keyring protects: the password on disk, and from the other users of the computer. A program that runs as you can usually read it: Credential Manager and an unlocked Secret Service hand it to any process of your session, while the Keychain asks you first unless the program is on the entry's access list.
  • All arguments are passed to the client through standard input (/args-from:stdin), so the password never appears in the process list (ps, Task Manager). FreeRDP 2 has no such option, so freerdp-tk refuses to start a FreeRDP 2 client rather than put the password on its command line.

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).

Hotkeys

The SDL client takes a few keys for itself: Right Shift plus Enter (fullscreen), R (resizable), G (grab the keyboard), M (minimize) and D (disconnect). So a capital D typed with the right Shift key ends the session. To move them to Right Alt + Right Shift, put this in ~/.config/freerdp/sdl-freerdp.json, the client's own settings file:

{ "SDL_KeyModMask": ["KMOD_RALT", "KMOD_RSHIFT"] }

It holds for every session of that client on that account, also without freerdp-tk.

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, adds the client to one wheel per platform (scripts/bundle_client.py), checks on a runner of each platform that the wheel installs and its client starts, and then uploads them all to PyPI, with the plain wheel and the sdist.

To move to a newer client, pin a release of rdp-release-kit and commit client.lock:

python scripts/bundle_client.py --pin 20261106.3

License

Apache-2.0, the same license as FreeRDP.

Metadata

Release files for freerdp-tk 0.4.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.4.0
File Size Uploaded Provenance Actions
freerdp_tk-0.4.0.tar.gz 126.7 kB With provenance Details for freerdp_tk-0.4.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for freerdp-tk 0.4.0
File Actions
freerdp_tk-0.4.0-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for freerdp_tk-0.4.0-py3-none-win_arm64.whl
freerdp_tk-0.4.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for freerdp_tk-0.4.0-py3-none-win_amd64.whl
freerdp_tk-0.4.0-py3-none-manylinux_2_34_x86_64.whl Python 3 none Linux glibc 2.34+ x86-64 Details for freerdp_tk-0.4.0-py3-none-manylinux_2_34_x86_64.whl
freerdp_tk-0.4.0-py3-none-manylinux_2_34_aarch64.whl Python 3 none Linux glibc 2.34+ ARM64 Details for freerdp_tk-0.4.0-py3-none-manylinux_2_34_aarch64.whl
freerdp_tk-0.4.0-py3-none-macosx_12_0_x86_64.whl Python 3 none macOS 12.0+ x86-64 Details for freerdp_tk-0.4.0-py3-none-macosx_12_0_x86_64.whl
freerdp_tk-0.4.0-py3-none-macosx_12_0_arm64.whl Python 3 none macOS 12.0+ ARM64 Details for freerdp_tk-0.4.0-py3-none-macosx_12_0_arm64.whl
freerdp_tk-0.4.0-py3-none-any.whl Python 3 none any Details for freerdp_tk-0.4.0-py3-none-any.whl

Total release size: 62.1 MB

Release files / freerdp_tk-0.4.0.tar.gz

Download URL freerdp_tk-0.4.0.tar.gz
Size 126.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3945b5b963382b4e5fbfc941e3d0432c4c504511316a80e480f1731cf9d00bb4
BLAKE2b-256 checksum
How to use checksums
fe76bb1258bffb8a6520afcf173663269e89de517cf61bc25b1551c8048eb19b
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 Nov 6, 2026.

Transparency log

Release files / freerdp_tk-0.4.0-py3-none-win_arm64.whl

Download URL freerdp_tk-0.4.0-py3-none-win_arm64.whl
Size 8.6 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
01c78db7f9385a2cb4ed87f3e4100b0e0d0bcf71f8b775e0130c60e5a0839dc2
BLAKE2b-256 checksum
How to use checksums
d7d7838bd851d05dd636ff3a9e2d2ea0259f47c27ca16c1959608b83a71fd2d7
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 Nov 6, 2026.

Transparency log

Release files / freerdp_tk-0.4.0-py3-none-win_amd64.whl

Download URL freerdp_tk-0.4.0-py3-none-win_amd64.whl
Size 10.1 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
9e83c6defe9ecd62f718e1bfaa9f607e621279ee00494ca53e6c40ac8c0e1e1d
BLAKE2b-256 checksum
How to use checksums
779d1410843027b802593315643e68202314695a235f57af0f8e22d94bc26668
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 Nov 6, 2026.

Transparency log

Release files / freerdp_tk-0.4.0-py3-none-manylinux_2_34_x86_64.whl

Download URL freerdp_tk-0.4.0-py3-none-manylinux_2_34_x86_64.whl
Size 12.4 MB
Tags Linux glibc 2.34+ x86-64 Python 3
SHA-256 checksum
How to use checksums
ade14b80a902a284569c12938bdc7faa10ead83c726de360bd66c53b71a4eb8d
BLAKE2b-256 checksum
How to use checksums
7423ddc2291878435ad2fd40574145ae922cf75d63172fed7575c86f0f9839f8
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 Nov 6, 2026.

Transparency log

Release files / freerdp_tk-0.4.0-py3-none-manylinux_2_34_aarch64.whl

Download URL freerdp_tk-0.4.0-py3-none-manylinux_2_34_aarch64.whl
Size 11.9 MB
Tags Linux glibc 2.34+ ARM64 Python 3
SHA-256 checksum
How to use checksums
be5fd5e3bde504ae2cf5930ba4013d43db85ad1afb3af602c8f7054675f75ec2
BLAKE2b-256 checksum
How to use checksums
0112a2b62d3d435e641282ac62b91e2954a4730f338fc369dd39020a55fb8c3d
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 Nov 6, 2026.

Transparency log

Release files / freerdp_tk-0.4.0-py3-none-macosx_12_0_x86_64.whl

Download URL freerdp_tk-0.4.0-py3-none-macosx_12_0_x86_64.whl
Size 10.1 MB
Tags Python 3 macOS 12.0+ x86-64
SHA-256 checksum
How to use checksums
992c523b3ced5670bbca1faf5b61b2d92fdd9a2e2451263c1a993668a334d7a4
BLAKE2b-256 checksum
How to use checksums
b2832968fd69fa2d5f312de478f0456d95ea8ff3bc762b56573be832a68d96d9
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 Nov 6, 2026.

Transparency log

Release files / freerdp_tk-0.4.0-py3-none-macosx_12_0_arm64.whl

Download URL freerdp_tk-0.4.0-py3-none-macosx_12_0_arm64.whl
Size 8.8 MB
Tags Python 3 macOS 12.0+ ARM64
SHA-256 checksum
How to use checksums
0317b6157ad2c069e3fb40ef2732c2c1e524ffe044d4a3eea8069c65d25bf266
BLAKE2b-256 checksum
How to use checksums
2729fd24fffc44db9e81233e7a57101e1c69448cd2062abdb8a24e8df32d80dc
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 Nov 6, 2026.

Transparency log

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

Download URL freerdp_tk-0.4.0-py3-none-any.whl
Size 33.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
95ad11c1911ca067ea740073aed944b1d5429e0c38f6fa4a3f906c315fb1667a
BLAKE2b-256 checksum
How to use checksums
7847f226ab03fb958fc24ef71e9f0f856d5c57b19b3224bfa8479cd9ae579a3c
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 Nov 6, 2026.

Transparency log

Security for freerdp-tk 0.4.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

All 8 files in this release have been uploaded with provenance metadata.

Select from 8 files

Attestation for freerdp_tk-0.4.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 Nov 6, 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