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).
1 maintainer
Release files for pysubs2 1.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pysubs2-1.9.0.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pysubs2-1.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.2 MB
Release files / pysubs2-1.9.0.tar.gz
| Download URL | pysubs2-1.9.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4592405e5d961e23cd39c81e2875fb85c30346ae37d100f144cd7fd8ec560e42
|
|
BLAKE2b-256 checksum How to use checksums |
f2209071b8b0012d9102e90292c71fe3f1181c33e772e28cbabb4779c0087603
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.
Transparency logRelease files / pysubs2-1.9.0-py3-none-any.whl
| Download URL | pysubs2-1.9.0-py3-none-any.whl |
|---|---|
| Size | 48.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
83f1979cb7e064294f0c8473ef672ca2e5c0a7172bbf8ae9b4337899d5cdf01f
|
|
BLAKE2b-256 checksum How to use checksums |
4f436b89c84f5a6753b1dbc43b8d010443b8f2314a2b94f34e448975d115c962
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.
Transparency log
