Installation¶

TGPy is a command line application that connects to your account much like a Telegram app on a new device.

You can install and run TGPy on your computer, but you might have to use a remote server to have TGPy available 24/7.

Warning

Make sure you run TGPy on a trusted machine — that is, no one except you can read TGPy files on the computer. Anyone with access to TGPy files can steal your Telegram account.

And the other way round: anyone with access to your Telegram account has access to the machine TGPy is running on.

It’s recommended to use pipx or Docker.

How to install using pipx¶

pipx is a package manager for Python command line applications.

Make sure you have Python 3.10 or above installed.

Get pipx if you don’t have it:

UbuntuArchFedoraOther LinuxWindowsmacOS

sudo apt update
sudo apt install pipx
pipx ensurepath

sudo pacman -Sy python-pipx
pipx ensurepath

sudo dnf install pipx
pipx ensurepath

Install pipx with your package manager.
```
pipx ensurepath
```

python3 -m pip install --user pipx
python3 -m pipx ensurepath

brew install pipx
pipx ensurepath

Now install TGPy:
```
pipx install tgpy
```
And start it:
```
tgpy
```

Follow the instructions to connect your Telegram account for the first time. When it’s ready, try sending ping() to any chat to check if TGPy is running.

How to install using Docker¶

docker pull tgpy/tgpy
docker run -it --rm -v /tgpy_data:/data tgpy/tgpy

Follow the instructions to connect your Telegram account for the first time. When it’s ready, try sending ping() to any chat to check if TGPy is running.

Updating to the latest version¶

When new updates arrive, you can get them with a TGPy function or from shell.

From Telegram messageFrom shell using pipxFrom shell using docker

update()

pipx upgrade tgpy

docker pull tgpy/tgpy

Then re-run:

docker run -it --rm -v /tgpy_data:/data tgpy/tgpy

Running in background¶

To get TGPy running in background, you need to additionally configure systemd, docker compose, or similar. Instructions are coming.

Data storage¶

Config, session, and modules are stored in ~/.config/tgpy directory (unless you’re using Docker.) You can change this path via TGPY_DATA environment variable.

Using proxy¶

If you require proxy to connect to Telegram, do the following:

Launch TGPy and provide api_id and api_hash, then quit.

Open config.yml file (see Data storage above) and add your proxy settings here:

core:
    api_hash: ...
    api_id: ...
    proxy:
        proxy_type: socks5
        addr: ...
        port: ...
        username: ...
        password: ...

Run TGPy normally

API secrets as environment variables¶

It's possible to provide Telegram API ID and hash through environment variables TGPY_API_ID and TGPY_API_HASH.