pysubs2

pysubs2 is a Python library for editing subtitle files. It’s based on SubStation Alpha, the native format of Aegisub; it also supports SubRip (SRT), MicroDVD, MPL2, TMP, WebVTT, TTML and SAMI formats and OpenAI Whisper captions.

Goal of this library is to provide practical, robust handling for subtitle files found in the wild (with all their questionable syntax). Internally, everything is converted to a representation based on ASS, which is relevant if you want to process formatting. Support for production/broadcast subtitle formats (or subtitle features beyond what ASS can express) is not really a goal of the library; however, please open an issue if you have a use-case where using this library would make sense to you.

Based on code originally created in 2011, in development ever since. Thanks to all users and contributors over the years!

Quick links: Documentation · Issues · Contributing · Source code

Usage

For more information, please see the tutorial and API reference in the Documentation.

import pysubs2
subs = pysubs2.load("my_subtitles.ass", encoding="utf-8")
subs.shift(s=2.5)
for line in subs:
    line.text = "{\\be1}" + line.text
subs.save("my_subtitles_edited.ass")

There is also a small CLI tool for batch conversion and retiming.

pip install pysubs2
pysubs2 --shift 0.3s *.srt
pysubs2 --to srt *.ass

Installation

Simply uv add pysubs2 or pip install pysubs2.

The library itself is pure Python, with no additional dependencies.

Contributing

If you'd like to contribute code to the library, see CONTRIBUTING.md.

License

pysubs2 is licensed under the MIT license (see LICENSE.txt).

Download files

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

Source Distribution

pysubs2-1.9.0.tar.gz (1.1 MB view details)

Uploaded Aug 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pysubs2-1.9.0-py3-none-any.whl (48.2 kB view details)

Uploaded Aug 16, 2026 Python 3

File details

Details for the file pysubs2-1.9.0.tar.gz.

File metadata

Download URL: pysubs2-1.9.0.tar.gz
Upload date: Aug 16, 2026
Size: 1.1 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pysubs2-1.9.0.tar.gz
Algorithm	Hash digest
SHA256	`4592405e5d961e23cd39c81e2875fb85c30346ae37d100f144cd7fd8ec560e42`
MD5	`3c81821d4622894eda1f4e601ab63d77`
BLAKE2b-256	`f2209071b8b0012d9102e90292c71fe3f1181c33e772e28cbabb4779c0087603`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pysubs2-1.9.0.tar.gz:

Publisher: release.yml on tkarabela/pysubs2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pysubs2-1.9.0.tar.gz
- Subject digest: 4592405e5d961e23cd39c81e2875fb85c30346ae37d100f144cd7fd8ec560e42
- Sigstore transparency entry: 2492113720
- Sigstore integration time: Aug 16, 2026
Source repository:
- Permalink: tkarabela/pysubs2@34d6ca5534ffd46cfa460d73aff79521eded2055
- Branch / Tag: refs/tags/1.9.0
- Owner: https://github.com/tkarabela
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@34d6ca5534ffd46cfa460d73aff79521eded2055
- Trigger Event: workflow_dispatch