.. image:: https://img.shields.io/pypi/v/telnetlib3.svg :alt: Latest Version :target: https://pypi.python.org/pypi/telnetlib3

.. image:: https://img.shields.io/pypi/dm/telnetlib3.svg?logo=pypi :alt: Downloads :target: https://pypi.python.org/pypi/telnetlib3

.. image:: https://codecov.io/gh/jquast/telnetlib3/branch/master/graph/badge.svg :alt: codecov.io Code Coverage :target: https://codecov.io/gh/jquast/telnetlib3/

.. image:: https://img.shields.io/badge/Linux-yes-success?logo=linux :alt: Linux supported :target: https://telnetlib3.readthedocs.io/

.. image:: https://img.shields.io/badge/Windows-yes-success?logo=windows :alt: Windows supported :target: https://telnetlib3.readthedocs.io/

.. image:: https://img.shields.io/badge/MacOS-yes-success?logo=apple :alt: MacOS supported :target: https://telnetlib3.readthedocs.io/

.. image:: https://img.shields.io/badge/BSD-yes-success?logo=freebsd :alt: BSD supported :target: https://telnetlib3.readthedocs.io/

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.

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
<https://man7.org/linux/man-pages/man1/locale.1.html>`_.

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 <https://muds.modem.xyz>`_ and `BBSs servers
<https://bbs.modem.xyz>`_:

- 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

# or with TLS (compression auto-disabled over TLS, CRIME/BREACH mitigation)
telnetlib3-client --ssl dunemud.net 6788

# 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 client passively accepts compression when offered by the server, and the server does not advertise compression. Compression is automatically disabled over TLS connections to avoid CRIME/BREACH attacks.

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.

Legacy telnetlib

This library contains an unadulterated copy of Python 3.12's telnetlib.py_, from the standard library before it was removed in Python 3.13.

To migrate code, change import statements:

.. code-block:: python

# OLD imports:
import telnetlib

# NEW imports:
import telnetlib3

telnetlib3 did not provide server support, while this library also provides both client and server support through a similar Blocking API interface.

See sync API documentation_ for details.

Quick Example

A simple telnet server:

.. code-block:: python

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:

.. code-block:: python

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

The following RFC specifications are implemented:

rfc-727_, "Telnet Logout Option," Apr 1977.
rfc-779_, "Telnet Send-Location Option", Apr 1981.
rfc-854_, "Telnet Protocol Specification", May 1983.
rfc-855_, "Telnet Option Specifications", May 1983.
rfc-856_, "Telnet Binary Transmission", May 1983.
rfc-857_, "Telnet Echo Option", May 1983.
rfc-858_, "Telnet Suppress Go Ahead Option", May 1983.
rfc-859_, "Telnet Status Option", May 1983.
rfc-860_, "Telnet Timing Mark Option", May 1983.
rfc-885_, "Telnet End of Record Option", Dec 1983.
rfc-930_, "Telnet Terminal Type Option", Jan 1984.
rfc-1073_, "Telnet Window Size Option", Oct 1988.
rfc-1079_, "Telnet Terminal Speed Option", Dec 1988.
rfc-1091_, "Telnet Terminal-Type Option", Feb 1989.
rfc-1096_, "Telnet X Display Location Option", Mar 1989.
rfc-1123_, "Requirements for Internet Hosts", Oct 1989.
rfc-1184_, "Telnet Linemode Option (extended options)", Oct 1990.
rfc-1372_, "Telnet Remote Flow Control Option", Oct 1992.
rfc-1408_, "Telnet Environment Option", Jan 1993.
rfc-1571_, "Telnet Environment Option Interoperability Issues", Jan 1994.
rfc-1572_, "Telnet Environment Option", Jan 1994.
rfc-2066_, "Telnet Charset Option", Jan 1997.

.. _rfc-727: https://www.rfc-editor.org/rfc/rfc727.txt .. _rfc-779: https://www.rfc-editor.org/rfc/rfc779.txt .. _rfc-854: https://www.rfc-editor.org/rfc/rfc854.txt .. _rfc-855: https://www.rfc-editor.org/rfc/rfc855.txt .. _rfc-856: https://www.rfc-editor.org/rfc/rfc856.txt .. _rfc-857: https://www.rfc-editor.org/rfc/rfc857.txt .. _rfc-858: https://www.rfc-editor.org/rfc/rfc858.txt .. _rfc-859: https://www.rfc-editor.org/rfc/rfc859.txt .. _rfc-860: https://www.rfc-editor.org/rfc/rfc860.txt .. _rfc-885: https://www.rfc-editor.org/rfc/rfc885.txt .. _rfc-930: https://www.rfc-editor.org/rfc/rfc930.txt .. _rfc-1073: https://www.rfc-editor.org/rfc/rfc1073.txt .. _rfc-1079: https://www.rfc-editor.org/rfc/rfc1079.txt .. _rfc-1091: h

Telnetlib3

Install / Use

README

Introduction

Command-line Utilities

Asyncio Protocol

Blocking API

Legacy telnetlib

Quick Example

Features