trzsz: rz and sz file transfers that support tmux

Why trzsz addresses the tmux gap in lrzsz

trzsz addresses a narrow but persistent problem in interactive file transfer. The conventional lrzsz workflow uses `rz` to receive files on a remote host and `sz` to send them to the local system. The README states that this workflow is not compatible with tmux. That restriction becomes significant when an engineer connects through several layers, such as a laptop, host A, host B, a Docker container, and a tmux session. Although SSH connects the machines, copying a file across the whole route with separate `scp` or `sftp` operations is inconvenient.

trzsz keeps file movement inside the terminal session but substitutes `trz` for uploads and `tsz` for downloads. It is intended for developers, system administrators, and researchers who already use interactive terminals. The supported client list includes iTerm2, tabby, electerm, ttyd, and the purpose-built `trzsz-ssh` client. A native terminal can also participate when the local Go version is used through `trzsz ssh`.

This is not simply a wrapper around the same tmux limitation. The project was created because tmux was not expected to add support for the existing `rz` and `sz` mechanism. trzsz instead provides its own compatible transfer commands. That design explains why both the local and remote installations matter. A server package without a compatible local terminal or client may leave the operator unable to complete the transfer.

The README also distinguishes tmux placement. If tmux runs on the local computer, it describes iTerm2 control-mode integration, local use of `trzsz ssh`, or `tssh` after tmux. If tmux runs on a jump server, it gives corresponding options including `trzsz -r ssh`. This matters during deployment because installing trzsz only at the final shell may not be enough for an interactive session.

How trz and tsz move data through the terminal

The public interface consists of two commands with closely related roles. `trz` receives files into a remote destination and behaves like `rz`. Its optional positional argument names the path where files are saved, with the current directory as the default. `tsz` sends one or more named files from the remote system and behaves like `sz`. Both commands expose controls for progress output, binary mode, control-character escaping, overwrites, buffer size, and timeout.

The documented options expose the transfer as a chunked operation. For both commands, `-B N, --bufsize N` sets the maximum buffer chunk size, with a default of 10M and a documented range from 1K to 1G. `-t N, --timeout N` applies to each buffer chunk and defaults to 20 seconds. A non-positive timeout means that the operation never times out. These settings give operators explicit control over chunk size and waiting behavior over a particular SSH route.

For binary content, `-b` selects binary transfer mode, which the manual describes as faster for binary files. The `-e` option escapes all known control characters. This can matter when terminal control sequences appear in transferred text, although the README does not define every character class involved. Progress mode is not limited to a spinner: the documented display includes the current file name, progress, size, speed, and remaining time. The `-q` option hides the progress bar when that output is unnecessary.

The repository contains separate directories for `trzsz-libs`, `trzsz-svr`, the main `trzsz` package, and `trzsz-iterm2`. That layout indicates reusable libraries, server-side code, and terminal integration code. The README does not document the wire protocol or the responsibilities of each internal module in enough detail to use the directory names as a public extension API. Engineers should rely on the documented command interface instead of importing undocumented internals.

Installing the server component for a first SSH transfer

The first deployment requirement is an implementation on the server where `trz` or `tsz` must run. The Go version is marked as recommended and has a separate installation guide. For this Python repository, the README documents the following Python 3 installation command:

sudo python3 -m pip install --upgrade trzsz

This installs or upgrades the package through Python's `pip` installer. The README also states that `sudo` is unnecessary when the selected installation path is already writable and included in `PATH`. It gives `~/.local/bin` as an example of such a path.

Homebrew is another documented installation route. Its complete command sequence is:

brew update
brew install trzsz

The first command updates Homebrew's package metadata, and the second installs trzsz. Node.js is also listed as an implementation:

sudo npm install -g trzsz

That command performs a global npm installation and may select a different implementation from the Python package. The README states that the Go, Python, and JavaScript versions are compatible with one another, which permits some deployment flexibility across local and remote machines. Compatibility does not remove the need for a local component that can carry transfers from the user's terminal.

The next step is therefore outside the server package itself. For a normal graphical terminal, install its documented integration. For a native terminal, use the local Go implementation through `trzsz ssh`. For a dedicated client, use `trzsz-ssh` through `tssh`. The README points to separate documentation for each setup and does not include enough installation detail to reproduce them here. After the remote package is on `PATH` and the local integration is configured, the commands `trz` and `tsz` form the upload and download interface.

Performing the first trzsz upload and download

Begin with a supported local terminal or with `tssh`, connect to the server, and confirm that the remote shell can invoke trzsz. An upload without a destination path uses the current remote directory:

trz

The terminal should enter its documented transfer interaction and show progress unless quiet mode is selected. The positional path can change the save location, although the README does not provide a concrete command using a custom destination, so that variation should be obtained from `trz` help on the installed system.

Directory uploads have a dedicated mode. The exact documented command is:

trz -d

`-d` selects `--directory`. The manual also defines `-r` as equivalent to `-d` for recursive directory handling. Neither option is presented as filesystem mirroring. The README does not state that `trz -d` preserves symbolic links, permissions, timestamps, empty directories, or other special filesystem entries.

For an existing destination file, the documented overwrite command is:

trz -y

The README says this overwrites existing files and automatically resumes from a breakpoint. This makes the flag relevant after an interrupted transfer, but the documentation does not explain how the project handles a destination whose contents changed before the resumed attempt. Test this behavior with expendable data before using it where overwriting matters.

Downloads use `tsz` and require file arguments. For directory downloads, the README gives this exact form:

tsz -d xxx

Here, `xxx` is the documentation's placeholder for the directory being sent. A plain `tsz` invocation sends the named files requested by the command. During either direction, `ctrl + c` stops a transfer, while `-q`, `-b`, `-e`, `-B N`, and `-t N` provide the corresponding progress, binary, escaping, buffer, and timeout controls documented for both commands.

Chunk tuning, interruption, and filesystem limits

Buffer and timeout settings are the most direct controls documented for long or unstable SSH routes. The default maximum buffer chunk is 10M, and each chunk times out after 20 seconds by default. Increasing either value changes the transfer operation rather than merely changing its display. A larger chunk must finish within the configured timeout, while a non-positive timeout disables expiration for that chunk. Values outside the documented 1K to 1G buffer range are not supported by the stated interface.

Resume is enabled through `-y`, according to the README. That command both permits overwriting and initiates automatic breakpoint resume when appropriate. This design is convenient for an interrupted interactive session, but it also introduces questions that the manual does not answer. It does not specify whether chunks are verified with a checksum, how renamed files are represented, or whether a source file can change during a resumed transfer. Those omissions limit how confidently the feature can be mapped onto automated synchronization requirements.

Directory transfer has a similar boundary. The presence of `-d` confirms support for directories and files, but it does not establish parity with tools designed for filesystem replication. The README does not document delete reconciliation, permissions, symbolic links, sparse files, extended attributes, or preservation of modification times. A transfer may therefore be useful for moving a project tree without becoming a dependable replacement for a metadata-aware synchronization workflow.

Cancellation is documented through `ctrl + c`, and the README says it stops gracefully. It does not specify the command's exact partial-file cleanup behavior after cancellation. Operators should test cancellation before leaving only one copy of an important file. These are real adoption constraints because file transfer tools are often selected for what they guarantee around failure, not only for their normal-path speed.

trzsz versus scp, sftp, and rsync on SSH

The closest conventional alternatives are `scp`, `sftp`, and `rsync` over SSH. Their main difference is interaction. trzsz makes upload and download operations part of an active terminal exchange, while the alternatives expose separate commands, subsystems, or synchronization workflows. For a simple direct SSH connection, `scp` or `sftp` may require fewer trzsz-specific components because no terminal-aware transfer integration has to be installed.

trzsz becomes more relevant when the path includes tmux, a jump host, or a container and the engineer already has a remote shell open. The README uses the chain from laptop to host A to host B to Docker to tmux as the motivating case. In that setting, being able to invoke `trz` or `tsz` within the session avoids reconstructing a separate file-copy route for every destination. The displayed progress and transfer result also fit an interactive workflow.

`rsync` addresses a different requirement when the objective is repeatable tree synchronization. trzsz documents directory transfer as a command option, not as a documented reconciliation algorithm. It does not provide evidence here of comparisons, deletion propagation, metadata retention, or noninteractive daemon behavior. For automation where those semantics matter, `rsync` or another transfer system selected for those exact requirements is easier to justify.

The trade-off is therefore clear. trzsz adds local-terminal cooperation and tmux support, but it also requires compatible components at the relevant ends of the session. It is the wrong tool for a pipeline with no interactive terminal, and it is the right tool for engineers who need interactive transfers through the layered SSH routes described by the project.

MIT terms and recent trzsz releases

The repository identifies trzsz as MIT licensed. Its license text permits use, copying, modification, merging, publication, distribution, sublicensing, and sale, provided the copyright and permission notice is included in copies or substantial portions of the software. The license also disclaims warranty and limits the author's liability to the extent permitted by law. These are the repository's stated terms, not legal advice for a particular deployment.

The Python package metadata in `setup.py` includes the classifier `Development Status :: 5 - Production/Stable`. That is a package classification rather than a guarantee about every supported implementation or terminal integration. The repository is not archived, and its last push was on 2026-08-28. Recent releases include v1.1.7 on 2026-08-28 and v1.1.6 on 2026-08-22, following v1.1.5 from 2024-01-20. These repository facts establish recent project activity, while leaving platform-specific upgrade behavior undocumented.

The README does not provide a formal upgrade guide, migration checklist, or compatibility matrix for local and remote versions. It does state that the Go, Python, and JavaScript versions are compatible with one another. Upgrading a server implementation may still require checking the terminal integration and running both transfer directions afterward. A practical first check is a new file upload and download, followed by a directory transfer and an interrupted `-y` operation if resumed transfers are part of the workflow. The final judgement depends on those documented commands working across the exact local client, server implementation, and tmux arrangement in use.

Editorial conclusion

Adopt trzsz when engineers routinely move files through interactive SSH sessions that include tmux, especially across jump hosts or containers where scp and sftp are inconvenient. Do not choose it for unattended distribution or workflows that require documented metadata preservation and automated file reconciliation. Before deployment, verify local terminal support, choose the server implementation, and test a directory transfer plus an interrupted upload against the intended SSH path.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. trzsz/trzsz on GitHub