Skip to content

Installation

This guide will help you install tgdl on your system.

Requirements

Before installing tgdl, ensure you have:

  • Python 3.7 or higher installed
  • pip package manager
  • Internet connection

Installation Methods

The easiest way to install tgdl is using pip:

pip install tgdl

Method 2: Install with pipx (Isolated)

For a cleaner installation that doesn't interfere with system packages:

# Install pipx first (if not already installed)
pip install pipx
pipx ensurepath

# Install tgdl
pipx install tgdl

Method 3: Install from Source

For the latest development version:

# Clone the repository
git clone https://github.com/kavidu-dilhara/tgdl.git
cd tgdl

# Install in development mode
pip install -e .

Verify Installation

After installation, verify that tgdl is installed correctly:

tgdl --version

You should see the version number:

tgdl, version 1.1.4

Platform-Specific Instructions

Using Command Prompt or PowerShell:

# Install
pip install tgdl

# Verify
tgdl --version

Windows PATH

If tgdl command is not found, add Python Scripts directory to PATH: 

C:\Users\<YourUsername>\AppData\Local\Programs\Python\Python3x\Scripts\

Using terminal:

# Install for current user
pip install --user tgdl

# Or system-wide (requires sudo)
sudo pip install tgdl

# Verify
tgdl --version

Add to PATH

If command not found, add to your ~/.bashrc or ~/.zshrc: 

export PATH="$HOME/.local/bin:$PATH"

Using terminal:

# Install
pip3 install tgdl

# Verify
tgdl --version

Homebrew Python

If using Homebrew Python, pip3 is recommended over pip.

Virtual Environment (Optional)

For isolated installation:

# Create virtual environment
python -m venv telegram-downloader
source telegram-downloader/bin/activate  # Linux/macOS
# or
telegram-downloader\Scripts\activate  # Windows

# Install tgdl
pip install tgdl

Updating tgdl

To update to the latest version:

pip install --upgrade tgdl

To update to a specific version:

pip install tgdl==1.1.4

Uninstallation

To remove tgdl:

pip uninstall tgdl

Data Preservation

Uninstalling tgdl does NOT delete:

  • Your configuration files (~/.tgdl/)
  • Your downloaded files (downloads/)
  • Your session data

To remove these manually, delete the .tgdl folder in your home directory.

Dependencies

tgdl automatically installs these dependencies:

  • telethon (>=1.42.0) - Telegram client library
  • click (>=8.3.0) - CLI framework
  • tqdm (>=4.67.1) - Progress bars
  • aiofiles (>=25.1.0) - Async file operations
  • cryptography (>=43.0.0) - Credential encryption

Troubleshooting Installation

Issue: pip command not found

Solution: Install pip first:

# Linux/macOS
python -m ensurepip --upgrade

# Windows
py -m ensurepip --upgrade

Issue: Permission denied

Solution: Install for user only:

pip install --user tgdl

Issue: Command not found after installation

Solution: Add Python scripts directory to PATH (see platform-specific instructions above).

Issue: SSL Certificate Error

Solution: Update pip and certificates:

pip install --upgrade pip certifi

Next Steps

Now that tgdl is installed, you need to:

  1. Get Telegram API credentials
  2. Complete the quick start guide
  3. Learn about authentication

Installation Complete!

You're ready to start using tgdl! Continue to the Quick Start guide.