by mohamed786


Deploy To Heroku

tgcf logo


The ultimate tool to automate custom telegram message forwarding.

GitHub license GitHub stars GitHub issues PyPI Twitter

Code Quality

Live-syncer, Auto-poster, backup-bot, cloner, chat-forwarder, duplicator, ...

Call it whatever you like! tgcf can fulfill your custom needs.

The key features are:

  1. Forward messages as "forwarded" or send a copy of the messages from source to destination chats.

    A chat can be anything: a group, channel, person or even another bot.

  2. Supports two modes of operation past or live.

    The past mode deals with all existing messages, while the live mode is for upcoming ones.

  3. You may login with a bot or an user account.

    Telegram imposes certain limitations on bot accounts. You may use an user account to perform the forwards if you wish.

  4. Perform custom manipulation on messages.

    You can filter, format, replace, watermark, ocr and do whatever else you need !

  5. Detailed wiki + Video tutorial.

    You can also get help from the community.

  6. If you are a python developer, writing plugins for tgcf is like stealing candy from a baby.

    Plugins modify the message before they are sent to the destination chat.

What are you waiting for? Star the repo and click Watch to recieve updates.

Video Tutorial

A youtube video is coming soon. Subscribe to get notified.


  • If you are an Windows user, who is not familiar with the command line, the Windows guide is for you.

  • To install tgcf on Android (Termux), there exists an installer script, that allows you to install all dependencies by running just a single line command. Read the guide for android to learn.

  • If you are familiar with Docker, you may read the docker guide for an isolated installation.

  • Otherwise for Linux/Mac, you may install tgcf via python's package manager pip.

    Note: Make sure you have Python 3.8 or above installed. Go to to download python.

    Open your terminal and run the following commands.

    pip install --upgrade tgcf

    To check if the installation succeeded, run

    tgcf --version


Configuring tgcf is easy. You just need two files in your present directory (from which tgcf is invoked).

  • .env : To define your environment variables easily.

  • tgcf.config.yml : An yaml file to configure how tgcf behaves.

In your terminal, just run tgcf live or tgcf past to start tgcf. It will prompt you to enter your phone no. or bot token, when you run it for the first time.

For more details run tgcf --help or read wiki.

Deploy to Cloud

Click on this link and get free 100$ on Digital Ocean.

DigitalOcean Referral Badge

NOTE You will get nothing if you directly sign up from Digital Ocean Home Page. Use the link above, or click on the big fat button above to get free 100$.

Deploying to a cloud server is an easier alternative if you cannot install on your own machine. Cloud servers are very reliable and great for running tgcf in live mode for a long time.

You can enjoy smooth one-click deploys to the major cloud providers.

Getting Help

  • First of all read the wiki and watch the videos to get started.

  • Type your question in GitHub's Search bar on the top left of this page, and click "In this repository". Go through the issues, discussions and wiki pages that appear in the result. Try re-wording your query a few times before you give up.

  • If your question does not already exist, feel free to ask your questions in the Discussion forum. Please avoid duplicates.

  • For reporting bugs or requesting a new feature please use the issue tracker of the repo.


PRs are most welcome! Read the contributing guidelines to get started.

If you are not a developer, you may also contribute financially to incentivise the development of any custom feature you need.