Skip to main content

Download subtitle from subscene

Project description


Downloads Published Version GitHub Release License: MIT

zsub downloads subtitles from and its persian clones such as

Table of Contents



If you want to handle rar files too, you need unrar. For most operating systems it can be downloaded from unrar official site. Windows users must download this self-extractor archive and run it. It will ask a folder to extract UnRar.exe file. Point to a PATH directory such as C:\Windows.
Also unix user could install this tool from their official or unofficial repositories.

If zsub can not find unrar executable in PATH, it will ignore rar files and prints a message instead.


Latest published release using pip3

python3 -m pip install --user --upgrade zsub
pip3 install --user --upgrade zsub

or install latest in progress version from github (not recommended)

pip3 install  --user --upgrade git+

How to Use


Since June 2019, subscene added google re-captcha. If user log in, this captcha will not be required.
At now (June 2019) it is easy to get a token even without user and password.


zsub dl -t Title of Movie or TV Series -l LNG1 [LNG2 ...] -d DESTINATION -s SITE -S -a|-A -o|-O -g|G

It searches title through specified site. If there are matches it asks user to choose the best match (multiple choice is acceptable, ust be in comma separated format) or selects automatically the first one.
Then language filters are applied. Also previously downloaded subtitles will be ignored.
It downloads remained links and saves them in "cache" folder. It will request multiple subtitles at same time to speed up the download process. These new subtitles are extracted to "unzip" folder. To help find subtitles easily, name of language will be appended to the names of extracted subtitles. To avoid replacing files in unzip folder, if it is needed then existing one is renamed.


  • -t is title to search. for example: -t riverdale or -t riverdale first season
  • -l is/are "space separated" language(s) that user interested in. It uses abbr for example: -l en fa it. Default: en
  • -d is unzip folder which downloaded subtitles will be extracted to. It supports . as current working directory and also relative paths to current working directory.
  • -s is site name to search through. (not full url, just name). supported:{subscene, subf2m, hastisub, xyz} Default: subscene
  • -oor -O determines if zsub must open the folder that subtitles are extracted into. -o for open the folder and -O for do nothing. Default: True (Open the folder)
  • -a or -A determines if zsub must automatically select best match (first result) from search results. -a for auto select and -A for ask user. Default: False (Ask for user to choose)
  • -g or -G determines if zsub must group extracted subtitles at destination by title and language. -g for grouping, -G for do nothing. default: -g
  • -S or --simulation: If you don't want to download all previously uploaded subs and just need to omit them on future download request, use these simulation switches. It creates empty zip file, instead of downloading subs. Then later if you search for this title it will ignore these files because it assumes this subtitle is already downloaded.


# if search keywords are distinctive enough, use auto select (-a)
zsub dl -t riverdale third season -l fa -a

# determine site. If site is not responding, zsub will choose first responding site automatically.
zsub dl -t game of thrones -s subscene

# movies, tv series, video musics are not different.
zsub dl -t how to train your dragon

# extract to a custom folder
# extract here and relative to here (both windows and unix)
zsub dl -t aquaman -d .
zsub dl -t aquaman -d ./children/to/here
zsub dl -t aquaman -d ../sibling/to/here
# absolute and relative path (unix)
zsub dl -t aquaman -d /absolute/path/to/a/destination
zsub dl -t aquaman -d ~/relative/path/to/home/directory
# absolute path (windows)
zsub dl -t aquaman -d 'D:\Movies\Aquaman\'


zsub info
zsub info -v {-t|-s|-n}
zsub info -vv

prints some useful information such as version and cache folder details.
With -v lists all downloaded titles with size and number of files sorted by title (-t). for sorting based on size (s) and number of files (n) use -s and -n.
With -vv lists titles in more details such as number of files for each language.

Extract Previously Downloaded Subtitles

zsub unzip -t Title of Movie or TV Series -l LNG1 [LNG2 ...] -d DESTINATION -a|-A -o|-O -g|-G

switches are same as zsub dl switches except there is no -s and -S. zsub searches through "cache" folder. Rest is same as the download process.


zsub config
zsub config --reset

cli for check and set default values for open_after, auto_select, site, language(s) and unzip folder. It reads and writes to config.ini file, located in config path.
Use --reset switch to overwrite existing config.ini with default values.

Batch mode

zsub batch --add -s SITE
zsub batch -s SITE -G -d DESTINATION
zsub batch --print
zsub batch --reset

Use --add switch to run a cli for adding titles to a list. This list can be used later by calling zsub batch command for checking new subtitles. It is suitable for TV Series that air weekly. By default, downloaded subtitles will be grouped at destination. To cancel this grouping use -G


zsub clean -t TITLE -l LNG1 [LNG2 ...] [-0]

searches cache directory for given title and language. then:

  • with -0 or --zero it will replace each downloaded files with empty zip files.
  • without -0 it will delete downloaded files completely.


zsub update

will check if there is a new version of zsub available.
Also if last check for update was before 7 days ago, zsub will check for update at next call automatically.


Create a zip archive from cache and config folder. It ccepts -d option for destination and -o|-O for opennig destination folder after creation completed.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for zsub, version 0.16.2
Filename, size File type Python version Upload date Hashes
Filename, size zsub-0.16.2-py3-none-any.whl (28.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size zsub-0.16.2.tar.gz (23.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page