Skip to main content
Latest Version Downloads codecov.io Code Coverage Linux supported Windows supported MacOS supported BSD supported

Introduction

telnetlib3 is a feature-rich Telnet Server, Client, and Protocol library for Python 3.9 and newer.

This library supports both modern asyncio and legacy Blocking API.

The python telnetlib.py module removed by Python 3.13 is also re-distributed as-is, as a backport. In Python 3.13+, pip install telnetlib3 provides a drop-in import telnetlib shim, so existing code using the legacy standard telnet client API continues to work without modification.

See the Guidebook for examples and the API documentation.

Command-line Utilities

The CLI utility telnetlib3-client is provided for connecting to servers and telnetlib3-server for hosting a server.

Both tools accept the argument --shell=my_module.fn_shell describing a python module path to a function of signature async def shell(reader, writer). The server also provides a --pty-exec argument allowing it to act as a telnet server for any CLI/TUI programs.

# telnet to utf8 roguelike server
telnetlib3-client nethack.alt.org

# or bbs,
telnetlib3-client xibalba.l33t.codes 44510

# automatic script communicates with a server
telnetlib3-client --shell bin.client_wargame.shell 1984.ws 666

# run a default shell server bound to 127.0.0.1 6023
telnetlib3-server

# or custom ip, port and shell
telnetlib3-server 0.0.0.0 1984 --shell=bin.server_wargame.shell

# host an external program with a pseudo-terminal (raw mode is default)
telnetlib3-server --pty-exec /bin/bash -- --login

# or host a program in linemode,
telnetlib3-server --pty-exec /bin/bc --line-mode

There are also two fingerprinting CLIs, telnetlib3-fingerprint and telnetlib3-fingerprint-server:

# host a server, wait for clients to connect and fingerprint them,
telnetlib3-fingerprint-server

# report fingerprint of the telnet server on 1984.ws
telnetlib3-fingerprint 1984.ws

Encoding

The default encoding of telnetlib3-client and server is set by the locale.

Without negotiation of BINARY transmission, all Telnet protocol text should be limited to ASCII text, by strict compliance of Telnet. Further, the encoding used should be negotiated by CHARSET RFC 2066 or by LANG using NEW_ENVIRON RFC 1572. Otherwise, a compliant telnet client should be limited to ASCII.

When these conditions are true, telnetlib3-server and telnetlib3-client allow automatic negotiation of any encoding in either direction supported by the python language, or any custom ATASCII, PETSCII, and big5bbs provided with telnetlib3.

However, from a February 2026 census of MUDs and BBSs servers:

  • 2.8% of MUDs and 0.5% of BBSs support bi-directional CHARSET

  • 18.4% of BBSs and 3.2% of MUDs support BINARY.

This means that connecting to large majority of BBSs or MUDs that transmit non-ascii, it will require manually specifying an encoding, eg.:

telnetlib3-client --encoding=cp437 20forbeers.com 1337

telnetlib3-client --encoding=big5bbs bbs.ccns.ncku.edu.tw 3456

Raw Mode

Some telnet servers, especially “retro” BBS systems or those designed for serial transmission but are connected to a TCP socket without any telnet negotiation may require the “raw” mode argument:

telnetlib3-client --raw-mode area52.tk 5200 --encoding=atascii

Go-Ahead (GA)

When a client does not negotiate Suppress Go-Ahead (SGA), the server sends IAC GA after output to signal that the client may transmit. This is correct behavior for MUD clients like Mudlet that expect prompt detection via GA.

If GA causes unwanted output for your use case, disable it:

telnetlib3-server --never-send-ga

For PTY shells, GA is sent after 500ms of output idle time to avoid injecting GA in the middle of streaming output.

Compression (MCCP)

MCCP2 (server-to-client) and MCCP3 (client-to-server) zlib compression are supported, widely used by MUD servers to reduce bandwidth:

# connect to a MUD that offers MCCP compression
telnetlib3-client dunemud.net 6789

# actively request compression from a server
telnetlib3-client --compression dunemud.net 6789

# reject compression even if the server offers it
telnetlib3-client --no-compression dunemud.net 6789

# host a MUD server that advertises MCCP2/MCCP3
telnetlib3-server --compression --shell=my_mud.shell

By default (without --compression or --no-compression), the telnetlib3-client passively accepts compression when offered by the server, and the telnetlib3-server does not advertise compression. Compression is automatically disabled over TLS connections.

Asyncio Protocol

The core protocol and CLI utilities are written using an Asyncio Interface.

Blocking API

A Synchronous interface, modeled after telnetlib.py (client) and miniboa (server), with various enhancements in protocol negotiation is also provided. See sync API documentation for more.

Quick Example

A simple telnet server:

import asyncio
import telnetlib3

async def shell(reader, writer):
    writer.write('\r\nWould you like to play a game? ')
    inp = await reader.readline()
    if inp:
        writer.echo(inp)
        writer.write('\r\nThey say the only way to win '
                     'is to not play at all.\r\n')
        await writer.drain()
    writer.close()

async def main():
    server = await telnetlib3.create_server(port=6023, shell=shell)
    await server.wait_closed()

asyncio.run(main())

A client that connects and plays the game:

import asyncio
import telnetlib3

async def shell(reader, writer):
    while True:
        output = await reader.read(1024)
        if not output:
            break
        if '?' in output:
            writer.write('y\r\n')
        print(output, end='', flush=True)
    print()

async def main():
    reader, writer = await telnetlib3.open_connection('localhost', 6023)
    await shell(reader, writer)

asyncio.run(main())

More examples are available in the Guidebook and the bin/ directory of the repository.

Features

Matching specifications:

  • Telnet protocol: Network Virtual Terminal data, IAC command escaping, and option negotiation with pending and refused states (rfc-854, rfc-855).

  • Commands: NOP, AYT, BRK, IP, AO, EC, EL, ABORT, EOF, SUSP, DM, and GA (rfc-854, rfc-858).

  • 8-bit binary transmission (rfc-856) and End of Record (rfc-885).

  • Echo (rfc-857) and Suppress Go-Ahead (rfc-858).

  • Status (rfc-859), Timing Mark (rfc-860), and Logout (rfc-727).

  • Terminal type (rfc-930, rfc-1091), terminal speed (rfc-1079), window size (rfc-1073), X display location (rfc-1096), and client location (rfc-779).

  • Environment negotiation (rfc-1408, rfc-1571, rfc-1572) including automatic encoding detection from LANG.

  • Character set negotiation (rfc-2066) with bidirectional code page lists.

  • Linemode (rfc-1184) with local editing, special line characters (SLC), and forwardmask.

  • Remote flow control (rfc-1372).

  • MUD standards: GMCP JSON packages (option 201), MSDP structured tables and arrays (69), MSSP server metadata (70), ZMP NUL-delimited messages (93), and MCCP2/MCCP3 zlib compression (86/87).

  • Public MUD codec helpers in telnetlib3.mud for GMCP, MSDP, MSSP, ZMP,

  • MCCP format auto-detection for zlib, gzip, and raw deflate streams.

See Specifications for the complete list of RFCs and MUD standards.

Features somewhat unique to this library:

  • Client and server fingerprinting: telnetlib3-fingerprint and telnetlib3-fingerprint-server probe core, legacy, and MUD telnet options, capture the TTYPE cycle, environment, SLC table, and banner, and save a deterministic JSON fingerprint, detection of telnet loops and wrong-direction negotiation.

  • Legacy BBS codecs: ATASCII, PETSCII, big5bbs, and Atari ST, including encoding-native keyboard and end-of-line translation for ATASCII and PETSCII.

  • TLS (TELNETS) in both client and server, including --tls-auto to accept TLS and plain telnet on the same port by detecting the TLS ClientHello.

  • PTY hosting with --pty-exec on POSIX systems: run any CLI or TUI program per connection, forwarding NAWS and TTYPE and switching between raw and cooked line mode.

  • Guard shells: --robot-check identifies a real terminal emulator by requesting a cursor position report, --pty-fork-limit queues excess connections with a busy shell, and ConnectionCounter enforces limits. ATCP, and AARDWOLF.

Further Reading

Further documentation available at https://telnetlib3.readthedocs.io/

Metadata

Release files for telnetlib3 5.0.3

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

Source distribution (sdist)

Source distribution for telnetlib3 5.0.3
File Size Uploaded Provenance Actions
telnetlib3-5.0.3.tar.gz 365.1 kB Without provenance Details for telnetlib3-5.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for telnetlib3 5.0.3
File Interpreter ABI Platform Actions
telnetlib3-5.0.3-py3-none-any.whl Python 3 none any Details for telnetlib3-5.0.3-py3-none-any.whl

Total release size: 736.0 kB

Release files / telnetlib3-5.0.3.tar.gz

Download URL telnetlib3-5.0.3.tar.gz
Size 365.1 kB
Tags Source
SHA-256 checksum
How to use checksums
71c845a3cc339d462cd54e5926b16e5fb38b775febf2fb3ce1137b6bb30e92fa
BLAKE2b-256 checksum
How to use checksums
486fb87a53d77072a9b2faa3f041e68d9266c49f3b965e3bf68db61d29ecbea7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0a5

Release files / telnetlib3-5.0.3-py3-none-any.whl

Download URL telnetlib3-5.0.3-py3-none-any.whl
Size 370.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e9a79de5c1b51145c080f566c5eca9dce1c8826595e1ef09b5569635376bd614
BLAKE2b-256 checksum
How to use checksums
8722899ddf638b56186ae7551b7b471d8a03b574cda162a2a329478faee300d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0a5

Security for telnetlib3 5.0.3

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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

This release

5.0.3 This release

2 release files No provenance

0.1

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