Skip to main content

Terminal client for telegram

Project description


Join telegram chat

Telegram terminal client.

tg screenshot


  • [X] view mediafiles: photo, video, voice/video notes, documents
  • [X] ability to send pictures, documents, audio, video
  • [X] reply, edit, forward, delete, send messages
  • [X] stickers
  • [X] notifications
  • [X] record and send voice msgs
  • [X] auto download files
  • [X] toggle chats: pin/unpin, mark as read/unread, mute/unmute
  • [X] message history


  • [ ] secret chats
  • [ ] list contacts
  • [ ] search
  • [ ] show users and their status in current chat
  • [ ] create new chat
  • [ ] bots (bot keyboard)


python3.8 required.

From pip:

pip3 install tg

From sources:

pip3 install python-telegram
git clone
cd tg
PYTHONPATH=. python3 tg/

Docker (voice recordings and notifications won't work):

docker run -it --rm tg

Arch Linux users can install from the AUR:

yay -S telegram-tg-git

Optional dependencies

  • terminal-notifier for Mac (used by default). You can change it to dunst for Linux or any other notifications program (see NOTIFY_CMD in configuration)
  • ffmpeg to record voice msgs and upload videos.
  • tdlib - in case of incompatibility with built in package. For example, macOS:
    brew install tdlib
    and then set in config TDLIB_PATH
  • urlview to choose urls when there is multiple in message, use URL_VIEW in config file to use another app (it should accept urls in stdin)
  • to open stickers and animated ones (thumbnail preview) you need to set in mailcap appropriate handler and have app which will open webp file:
    image/webp; mpv %s


Config file should be stored at ~/.config/tg/ This is simple python file.

Simple config:

PHONE = "[your phone number]"

Advanced configuration:

import os

# You can write anything you want here, file will be executed at start time
# You can keep you sensitive information in password managers or gpg
# encrypted files for example
def get_pass(key):
    # retrieves key from password store
    return os.popen("pass show {} | head -n 1".format(key)).read().strip()

PHONE = get_pass("i/telegram-phone")
# encrypt you local tdlib database with the key
ENC_KEY = get_pass("i/telegram-enc-key")

# log level for debugging, info by default
# path where logs will be stored (all.log and error.log)
LOG_PATH = "~/.local/share/tg/"

# If you have problems with tdlib shipped with the client, you can install and
# use your own, for example:
TDLIB_PATH = "/usr/local/Cellar/tdlib/1.6.0/lib/libtdjson.dylib"

# you can use any other notification cmd, it is simple python string which
# can format title, msg, subtitle and icon_path paramters
# In these exapmle, kitty terminal is used and when notification is pressed
# it will focus on the tab of running tg
NOTIFY_CMD = "/usr/local/bin/terminal-notifier -title {title} -subtitle {subtitle} -message {msg} -appIcon {icon_path} -sound default -execute '/Applications/ @ --to unix:/tmp/kitty focus-tab --no-response -m title:tg'"

# You can use your own voice recording cmd but it's better to use default one.
# The voice note must be encoded with the Opus codec, and stored inside an OGG
# container. Voice notes can have only a single audio channel.
VOICE_RECORD_CMD = "ffmpeg -f avfoundation -i ':0' -c:a libopus -b:a 32k {file_path}"

# You can customize chat and msg flags however you want.
# By default words will be used for readability, but you can make
# it as simple as one letter flags like in mutt or add emojies
    "online": "●",
    "pinned": "P",
    "muted": "M",
    # chat is marked as unread
    "unread": "U",
    # last msg haven't been seen by recipient
    "unseen": "✓",
    "selected": "*",
    "forwarded": "F",
    "new": "N",
    "unseen": "U",
    "edited": "E",
    "pending": "...",
    "failed": "💩",

# use this app to open url when there are multiple
URL_VIEW = 'urlview'

# Specifies range of colors to use for drawing users with
# different colors
# this one uses base 16 colors which should look good by default
USERS_COLORS = tuple(range(2, 16))

# to use 256 colors, set range appropriately
# though 233 looks better, because last colors are black and gray
# USERS_COLORS = tuple(range(233))

# to make one color for all users

# cleanup cache
# Values: N days, None (never)

Mailcap file

Mailcap file is used for deciding how to open telegram files (docs, pics, voice notes, etc.).

Example: ~/.mailcap

# media
video/*; mpv "%s"
audio/ogg; mpv --speed 1.33 "%s"
audio/mpeg; mpv --no-video "%s"
image/*; qView "%s"

# text
text/html; w3m "%s"
text/html; open -a Firefox "%s"
text/plain; less "%s"

# fallback to vim
text/*; vim "%s"


vi like keybindings are used in the project. Can be used commands like 4j - 4 lines down.

For navigation arrow keys also can be used.


  • j,k: move up/down
  • J,K: move 10 chats up/down
  • g: go to top chat
  • l: open msgs of the chat
  • m: mute/unmute current chat
  • p: pin/unpin current chat
  • u: mark read/unread
  • r: read current chat
  • ?: show help


  • j,k: move up/down
  • J,K: move 10 msgs up/down
  • G: move to the last msg (at the bottom)
  • l: if video, pics or audio then open app specified in mailcap file, for example:
    # Images
    image/png; qView "%s"
    audio/*; mpv "%s"
    if text, open in less (to view multiline msgs)
  • e: edit current msg
  • <space>: select msg and jump one msg down (use for deletion or forwarding)
  • <ctrl+space>: same as space but jumps one msg up
  • y: yank (copy) selected msgs with <space> to internal buffer (for forwarding) and copy current msg text or path to file to clipboard
  • p: forward (paste) yanked (copied) msgs to current chat
  • dd: delete msg for everybody (multiple messages will be deleted if selected)
  • i or a: insert mode, type new message
  • I or A: open vim to write long msg and send
  • v: record and send voice message
  • r,R: reply to a current msg
  • sv: send video
  • sa: send audio
  • sp: send picture
  • sd: send document
  • o: open url present in message (if multiple urls, urlview will be opened)
  • ]: next chat
  • [: prev chat
  • ?: show help
  • !: open msg with custom cmd

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tg, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size tg-0.3.0-py3-none-any.whl (67.8 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page