• ⚙️ Installation
  • Python & Git
  • Download
  • Requirements
• 🚩 Options
  • Connectivity
  • Login
  • File
  • Behaviour
  • Utility
  • Misc
• 🕹️ How to use?
  • Get API ID & HASH
  • Authorization
  • Get Started
  • Caption
    • Dynamic Caption
      • Variables
      • Path Methods
      • Time Index
      • Decimal Places
    • Formatting Modes
    • Caption Templates
  • Using Proxy
• 🪧 Limits
  • File Size
  • Thumbnail
  • Caption
• ❓ FAQ
• ⚒️ Contribution
• ⛑️ Need help!
• ❤️ Credits & Thanks

Git installation is optional if you prefer downloading stable releases zips of tg-upload using releases section.

1.Install Python & Git:

Prefer Python 3.11 for faster execution speed.

For Windows:

winget install Python.Python.3.11
winget install Git.Git

For Linux:

sudo apt-get update && sudo apt-get install -y python3.11 git pip

For MacOS:

brew install [email protected] git

For Termux:

pkg install python -y
pkg install git -y

2.Download tg-upload:

• For stable releases, download zip from here and unzip. (Recommended)

• To download beta releases, use git:

git clone https://github.com/TheCaduceus/tg-upload.git

Starting from release v1.0.1, tg-upload not support Termux anymore due to absence of some required dependencies. You may try older release to enjoy basic functionalities offered by tg-upload. Hence, any issue related with Termux will be rejected without any further investigation.

3.Change Directory:

cd tg-upload

4.Install requirements:

If your device already have required dependencies installed, then verify if their version and the version mentioned in 'requirements.txt' are same otherwise upgrade them. You can see their version by using tg-upload's -v flag.

pip install -r requirements.txt

5.Run the program:

python tg-upload.py -h

tg-upload provides multiple options known as flags to control overall behaviour of the program, flags are categorized as follows:

1.CONNECTIVITY FLAGS:

Connectivity flags controls how the program should establish connection to Telegram servers, helpful for those uses proxies to bypass ban imposed on Telegram by their ISP (or for increasing transfer speed) or for those prefer IPv6 to establish connection.

Learn here, how to configure proxies?

--ipv6 - Connect Telegram using device's IPv6. By default IPv4.
--proxy - Proxy name (in proxy.json) to use for connecting Telegram.

2.LOGIN FLAGS:

Login flags are responsible for controling behaviour of the program during authentication flow.

-p,--profile - Name of your new/existing session.
--info - Show your Telegram account details as JSON.
--api_id - Telegram API ID required to create new session.
--api_hash - Telegram API HASH required to create new session.
--phone - Phone number (international format) required to login as user.
--hide_pswd - Hide 2FA password using getpass.
--bot - Telegram bot token required to login as bot.
--logout - Revoke current session and delete session file.
--login_string - Session string to login without auth & creating session file.
--export_string - Generate & display session string using existing session file.
--tmp_session - Don't create session file for this login.
--login_only - Exit immediately after authorization process.

3.FILE FLAGS:

File flags are used to provide information about file/folder.

-l,--path - Path to the file or folder to upload.
-n,--filename - To upload data with custom name.
-i,--thumb - Path of thumbnail image (JPEG format) to be attached with given file.
-z,--caption - Caption text to be attached with file(s), markdown & HTML formatting allowed.
--duration - Duration of sent media in seconds.
--capjson - Caption name (in caption.json) to attach with given file(s).

4.BEHAVIOUR FLAGS:

Behaviour flags controls the behaviour of transmission.

-c,--chat_id - Identity of chat to send the file to? can be username, phone number (international format) or ID number. By default to Saved Messages.
--as_photo - Send given file as picture.
--as_video - Send given file as video.
--as_audio - Send given file as audio.
--as_voice - Send given file as voice.
--as_video_note - Send given file as video note.
--split - Split files in given bytes and upload.
--replace - Replace given character or keyword in filename. Requires two arguments including "text to replace" "text to replace from".
--disable_stream - Disable streaming for given video.
-b,--spoiler - Send media with spoiler animation.
--parse_mode - Set custom formatting mode for caption.
-d,--delete_on_done - Delete the given file after task completion.
-w,--width - Set custom width for video.
-e,--height - Set custom height for video.
-a,--artist - Set artist name of given audio file.
-t,--title - Set title of given audio file
-s,--silent - Send files silently to given chat.
-r,--recursive - Upload files recursively if path is a folder.
--prefix - Add given prefix text to each filename (prefix + filename) before upload.
--no_warn - Don't show warning messages.

5.UTILITY FLAGS:

Utility flags provides an easy way to directly use internal functions used by tg-upload without starting main client, hence there is no need to create or use existing session (--profile) to call them.

--file_info - Show basic file information.
--hash - Calculate & display hash of given file.
--split_file - Split file in given bytes, accepts only size & requires path using path flag.
--combine - Restore original file using part files produced by tg-upload. Accepts one or more paths.
--convert - Convert any image into JPEG format.

6.MISC FLAGS:

Flags that does not fit in above categories are listed in this category:

-h, --help - To get help message as well as availabe options.
--device_model - Overwrite device model before starting client, by default 'tg-upload', can be anything like your name or 'My Device'.
--system_version - Overwrite system version before starting client, by default installed python version, can be anything like 'Windows 11'.
-v,--version - Display current tg-upload & dependencies version.

1.Create a Telegram app:

Go to My Telegram and create an app and get its API_ID & API_HASH and save it somewhere securely and treat them as your bank password.

2.Login in tg-upload:

tg-upload supports login as user (using phone number or session string) or bot (using bot token or session string), you must pass the value of your API_ID (--api_id) & API_HASH (--api_hash) and a unique name for your session (--profile), to login as user you must pass your phone number (--phone) or to login as bot pass bot token (--bot).

python tg-upload.py --profile VALUE --api_id VALUE --api_hash VALUE --phone VALUE --login_only

now from next time whenever you need to perform any task, you just need to pass the profile name (--profile) which you used to create your session and you will be logged in without any authentication flow (until you terminate the session from Telegram app).

3.Get Started:

Hooray! now you are all set to use tg-upload. You can try out some sample commands that will help you to get started quickly:

Get help & options:

python tg-upload.py -h

Upload files/folder:

python tg-upload.py --profile VALUE --path VALUE --OTHER OPTIONAL FLAGS

Check versions:

python tg-upload.py -v

4.Dynamic Caption:

tg-upload provides variables that user can place in file's caption to make it dynamic, this variables are automtically replaced with their expected values. User must place variable name between {} to define it as a variable in string, here is the list of variables that tg-upload offers:

• {file_name} - Name of file without its format.
• {file_format} - Format of given file including '.'.
• {path} - Retrive particular value from path or exact path. (for advanced users)
• {creation_time[indice]} - File's creation time.
• {modification_time[indice]} - File's last modification time.
• {file_sha256} - Given file's SHA256.
• {file_md5} - Given file's MD5.
• {file_size_b} - Size of file in bytes.
• {file_size_kb} - Size of file in KB.
• {file_size_mb} - Size of file in MB.
• {file_size_gb} - Size of file in GB.

File's source variable {path} is both a variable and a function, calling it directly will simply return the full path of file while calling it with a given method will return value associated with that method, below are the methods that you can call with path:

• {path} - Return exact path of file.
• {path.parts} - A tuple giving access to the path’s various components. [example]
• {path.drive} - A string representing the drive letter or name, if any. [example]
• {path.root} - A string representing the (local or global) root, if any. [example]
• {path.anchor} - The concatenation of the drive and root. [example]
• {path.parents} - An immutable sequence providing access to the logical ancestors of the path. [example]
• {path.parent} - The logical parent of the path. [example]
• {path.name} - A string representing the final path component, excluding the drive and root, if any. [example]
• {path.suffix} - The file extension of the final component, if any. [example]
• {path.suffixes} - A list of the path’s file extensions. [example]
• {path.stem} - The final path component, without its suffix. [example]

For more detailed methods, click here. Some methods requires newer Python version.

File's creation/modification time variables {creation_time} and {modification_time} stores multiple values like year, month, day, hour, minute, second of creation/modification and they all have their own index value inside the variable and it should be passed with variable to get specific value, if creation time is unknown then last modification time will be passed or vice-versa and it also depends upon your operating-system:

• 0 - Year of creation/modification.
• 1 - Month of creation/modification.
• 2 - Day of creation/modification.
• 3 - Hour of creation/modification.
• 4 - Minute of creation/modification.
• 5 - Second of creation/modification.

Additionally, we can also limit number of decimal places to be shown in file size, like to limit number of decimals places to 2 we need to pass :.2f with a variable like {file_size_mb:.2f}.

One variable can be called multiple times in same caption and user must prevent writing any other keyword between {} otherwise tg-upload will raise KeyError indicating that given variable is not yet defined.

5.Formatting Modes:

Formatting and making caption attractive is cool! but sometime filename or output of any variable can mess our caption by injecting same tags which are used to format our plan text 💀, to tackle this error! tg-upload provide option to switch between different formatting modes to prevent misinterpretation of some tags in our caption:

• DEFAULT - Interpret both markdown & HTML tags in caption.
• MARKDOWN - Interpret only markdown tags and ignore HTML tags in caption.
• HTML - Interpret only HTML tags and ignore markdown tags in caption.
• DISABLED - Interpret nothing, keep caption as it is.

If you are using --caption flag then you can switch mode using --parse_mode flag else just change 'mode' key value in 'caption.json' in case of --capjson.

6.Caption Templates:

We can make & save our static & dynamic caption format in 'caption.json' with a name (required) and description (optional) so we don't have to write it again.

1.Open 'caption.json' file and edit it as following:

{
  "captionTemplateName": {
    "text" : "main caption text",
    "mode" : "DEFAULT",
    "description" : "An optional description to make recall easy."
  },
  ...more caption templates 
}

2.When needed, just mention the caption template name using --capjson flag.

Just like --caption flag, caption template also supports formatting using HTML or markdown. I already provided some general caption templates to make your work easy! :)

Using Proxy

Using proxy is completely optional step and can be used to bypass ban imposed by local authorities or for increasing transfer speed:

1.Rename 'proxy-sample.json' to 'proxy.json'

2.Fill the proxy details:

{
  "proxyName": {
    "scheme": "proxyScheme", # like socks5
    "hostname": "proxyHostname", # like 192.168.1.1
    "port": 1234, # like 8080, should be integer.
    "username": "proxyUsername", # optional, omit or keep empty if not required.
    "password": "proxyPassword" # optional, omit or keep empty if not required.
  },
  ...more proxies
}

3.While running tg-upload, just mention the proxy name using --proxy.

1.File size:

• 2GB for bots & freemium users.
• 4GB for premium users.

To upload larger files, use --split flag and tg-upload will automatically split all files in given size, to restore original file out of part files, simply use --combine flag and tg-upload will restore original file for you (remember to provide part file paths in ordered form 0,1,2,3...).

2.Thumbnail:

• Only JPEG format.
• Size should be 200 KB or below.
• Width & height should not be more than 320 pixels.

Starting from v1.0.5, tg-upload will automatically convert any other image format into JPEG format and you can also use --convert flag to do it manually and without starting the main client.

3.Caption:

• 1024 characters for all files & media.

1.Getting socket.send(), OSError(), TimeoutError(), Connection lost/reset…?

Such network related issues are most likely a result of a temporarily slow or inconsistent network connection and will eventually disappear automatically.

2.Can split or combine flags cause file corruption?

No, split & combine flags NEVER causes file corruption until its user side mistake like not providing .part file paths in correct format (0,1,2,3...). tg-upload follows commonly used & trusted technique to split or combine data.

3.Files are still usable/accessible in their splitted form?

Yes, some file extensions like .txt, .csv, .json etc are still usable in their splitted forms while some file extensions like .mkv, .exe, .mp3 etc are NOT usable until we combine them back.

4.For me upload speed is slow?

In many cases, users expect speed in mbps while tg-upload shows upload speed in MB/s where MB/s > mbps and this is where users get confused.

In fact, tg-upload have nothing to do with upload speed and it totally depends upon Telegram servers (generally 5-7 MB/s) and your internet connection including proxy. Check code to understand it in more better way.

5.How tg-upload able to upload larger files (upto 2GB) using bot profiles while Bot API limit it to just 50MB?

Its simple! tg-upload never make use of Bot API server which works as intermediate server to communicate with Telegram's MTProto while tg-upload directly uses MTProto API making it even more faster.

• Generally:🐢

You (JSON/HTTP) -> Bot API (MTProto) -> Telegram = Smaller & slower data transfer.

• tg-upload:⚡

You (MTProto) -> Telegram = Larger & direct data transfer.

Feel free to create a PR (to dev branch) if you have any valueable changes like adding new features or fixing bugs and not only including (but not limited to):

• Changing print statements' string.
• Refactoring code using AI tools.
• Typos in README.
• File rename.
• Changing default values unless it causing problems.
• Deleting existing features.

• Create an issue on GitHub.
• Subscribe Telegram channel.
• Ask questions or doubts here.
• Send a personal message to developer on Telegram.
• Tag on Twitter.

Dr.Caduceus: Owner & current maintainer of tg-upload.