Installation

Telegram Stats is available for download on both PyPI and Forgejo Packages.

Recommendation is to install it via PyPI with pipx:

pipx install telegramstats[markov]

If you are not interested in Markov chain generation support, you can omit the installation of markovify by not including the markov extra:

pipx install telegramstats[]

To change from one to the other, due to pipx limitations, you'll have to specify the --force flag:

pipx install --force telegramstats[markov]

Preparation

Before using Telegram Stats, you must have acquired a GDPR export of the chat(s) you want to compute stats about.

To perform the export, from Telegram Desktop:

1. Select a chat
2. Click on the vertical ellipsis menu on the top right corner of the window
3. Select Export chat history
4. Deselect all checkmarks
5. Change Format to Machine-readable JSON

Usage

Computing message counts by user

To determine how many messages each user has sent in one or more chats, you can use the single counts-by-user subcommand.

For example:

telegramstats single counts-by-user ./ChatExport_2025-11-14/result.json

If multiple exports are specified, message counts for all of them are summed together, and displayed in a single report:

telegramstats single counts-by-user ./ChatExport_2025-11-13/result.json ./ChatExport_2025-11-14/result.json

Generate a markovify chain

To create a markovify chain from the messages sent in one or more chats, and generate a few sample sentences from the resulting chain, you can use the single markovify-chain subcommand.

For example, to generate a model from a single chat, and store it as the chat.pickle file:

telegramstats single markovify-chain --output-file='./chat.pickle' ./ChatExport_2025-11-14/result.json

If multiple exports are specified, a single chain is created from the messages contained in both of them:

telegramstats single markovify-chain --output-file='./chat.pickle' ./ChatExport_2025-11-13/result.json ./ChatExport_2025-11-14/result.json

To change the state size of the generated Markov chain (the number of previous words that the chain takes into account before generating a new one) you can specify the --state-size='N' option, where N is the desired state size (larger values make sentences slightly more coherent but significantly less random):

telegramstats single markovify-chain --output-file='./chat.pickle' --state-size='2' ./ChatExport_2025-11-14/result.json

To only output a preview of the model, and not save the model as a file, on Linux you can specify the --output-file='/dev/null' option:

telegramstats single markovify-chain --output-file='/dev/null' ./ChatExport_2025-11-14/result.json

To generate more preview sentences from a single command invocation, you can specify the '--preview-size='N'` option, where N is the number of sentences you want to generate:

telegramstats single markovify-chain --output-file='/dev/null' --preview-size='1000' ./ChatExport_2025-11-14/result.json