Install & Compatibility
Where this runs
tested against v1.8.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.186s · 18.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.169s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SSAFile
✓ from pysubs2 import SSAFile
SSAFile is the main class for handling subtitle files.
SSAEvent
✓ from pysubs2 import SSAEvent
SSAEvent represents a single subtitle line.
make_time
✓ from pysubs2 import make_time
A utility function to create time values in milliseconds from H, M, S, MS.
load
✓ from pysubs2 import load
Function to load a subtitle file, an alias for SSAFile.load().
pysubs2
✓ import pysubs2
Commonly used for accessing top-level functions and classes (e.g., pysubs2.SSAFile, pysubs2.load).
This quickstart demonstrates how to load a subtitle file, add a new event, shift all event timings, modify an existing event's text, and save the result in a different format (ASS). It highlights the use of `pysubs2.load`, `pysubs2.SSAEvent`, `pysubs2.make_time`, and `subs.save` methods.
import pysubs2
import os
# Create a dummy SRT file for demonstration
dummy_srt_content = """
1
00:00:01,000 --> 00:00:03,000
Hello, world!
2
00:00:04,000 --> 00:00:06,000
This is a test subtitle.
"""
with open("input.srt", "w", encoding="utf-8") as f:
f.write(dummy_srt_content)
# Load the subtitle file
subs = pysubs2.load("input.srt", encoding="utf-8")
print(f"Loaded {len(subs)} subtitles.")
# Add a new subtitle event
subs.append(pysubs2.SSAEvent(
start=pysubs2.make_time(s=7),
end=pysubs2.make_time(s=9, ms=500),
text="A new subtitle added via pysubs2."
))
# Shift all subtitles by 1.5 seconds forward
subs.shift(s=1, ms=500)
# Modify an existing subtitle
if len(subs) > 0:
subs[0].text = "(Modified) " + subs[0].text
# Save the modified subtitles to a new ASS file
output_filename = "output_modified.ass"
subs.save(output_filename, format_="ass", encoding="utf-8")
print(f"Modified subtitles saved to {output_filename}.")
# Clean up dummy files
os.remove("input.srt")
os.remove(output_filename)
pysubs2 --version
Debug
Known issues
gotchaThe `pysubs2` command-line interface (CLI) works in-place by default, overwriting original subtitle files. Always use the `-o` or `--output-dir` options to specify an output location or pipe output to a new file to prevent accidental data loss.fixUse `python -m pysubs2 <infile> -o <outfile>` or `python -m pysubs2 --output-dir <directory> <files>` when using the CLI.
affects: All versions
gotchaWhen dealing with older or non-standard subtitle files, character encoding issues are common. `pysubs2` defaults to UTF-8, but you may need to explicitly specify a different `encoding` (e.g., 'latin-1', 'cp1252') during `load()` or `save()` operations. Version 1.7.0 introduced the `errors` parameter for better handling of unknown encodings.fixPass the `encoding='your-encoding'` argument to `pysubs2.load()` and `subs.save()`. For `load()`, consider `errors='surrogateescape'` for pass-through of unsupported bytes.
affects: All versions, especially prior to 1.7.0 for error handling.
gotchaFor frame-based formats like MicroDVD, proper retiming and conversion depend on knowing the video's framerate (FPS). If the FPS cannot be autodetected from the file, you must explicitly provide it using the `fps` argument during `pysubs2.load()` and `subs.save()` to ensure correct timing calculations.fixAlways pass `fps=<framerate_value>` to `pysubs2.load()` and `subs.save()` when working with frame-based subtitle formats if the framerate is not reliably embedded or detected.
affects: All versions
gotchaConverting from rich formats (like Advanced SubStation Alpha, ASS) to simpler formats (like SubRip, SRT) may result in the loss of complex styling, override tags, and positioning information, as the target format might not support these features.fixBe aware of the limitations of the target format. If preserving styling is critical, consider sticking to ASS or using the CLI's `--srt-keep-html-tags` and `--srt-keep-ssa-tags` options, which allow some tags to pass through to SRT output (though not all styling can be converted).
affects: All versions
gotchaThe `SSAEvent.plaintext` property is a convenience for getting text without override tags (`{\i1}`). However, directly *assigning* to `SSAEvent.plaintext` will strip *all* existing override tags from the subtitle, which might be an unintended loss of formatting.fixIf you need to modify text while preserving or selectively changing override tags, work directly with the `SSAEvent.text` attribute and manually manage the override tags within the string. Use `plaintext` for read-only access when unformatted text is needed.
affects: All versions
Errors
Common errors & fixes
UnicodeDecodeError: 'utf-8' codec can't decode byte
The subtitle file is encoded in a format other than UTF-8, but `pysubs2.load()` attempts to read it as UTF-8 by default.
fixSpecify the correct encoding when loading the file, e.g., `subs = pysubs2.load('your_file.srt', encoding='cp1252')` or `encoding='shift_jis'`. FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your/file.srt'
The file path provided to `pysubs2.load()` is incorrect, or the file does not exist at the specified location.
fixEnsure the file exists and provide the correct, absolute or relative path to the file.
ModuleNotFoundError: No module named 'pysubs2'
The `pysubs2` library has not been installed in the current Python environment.
fixInstall the library using pip: `pip install pysubs2`
AttributeError: 'Event' object has no attribute
Attempting to access an attribute or property that does not exist on an `Event` object (or similar `SubtitleFile` object), or mistyping a valid attribute name.
fixRefer to the `pysubs2` documentation for the correct attribute names (e.g., `event.text` instead of `event.content`, `subs.styles` instead of `subs.all_styles`).
Upgrade
Version history
1.8.1latest on PyPI · released Mar 19, 2026
Audit
Dependencies
No dependency data recorded yet.