Install & Compatibility
Where this runs
tested against v1.2.0.20260518 · 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.006s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.006s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
POFile
✓ from polib import POFile
POEntry
✓ from polib import POEntry
pofile
✓ import polib; po = polib.pofile(...)
This quickstart demonstrates basic usage of the `polib` library to create and manipulate .po files. When `types-polib` is installed alongside `polib`, static type checkers (like MyPy, Pyright, or PyCharm) will automatically use the provided type hints to analyze this code for type consistency and potential errors, without requiring any changes to the import statements.
import polib
# Create a new PO file
pofile = polib.POFile()
pofile.metadata = {
'Project-Id-Version': 'My Project 1.0',
'Report-Msgid-Bugs-To': 'you@example.com',
'POT-Creation-Date': '2023-01-01 00:00+0000',
'PO-Revision-Date': '2023-01-01 00:00+0000',
'Last-Translator': 'Your Name <you@example.com>',
'Language-Team': 'English <en@example.com>',
'MIME-Version': '1.0',
'Content-Type': 'text/plain; charset=utf-8',
'Content-Transfer-Encoding': '8bit',
}
# Add an entry
entry = polib.POEntry(
msgid='Hello world!',
msgstr='Hola mundo!',
occurrences=[('main.py', '10')],
comment='A greeting message'
)
pofile.append(entry)
# Add another entry with plural forms
entry_plural = polib.POEntry(
msgid='{} item',
msgid_plural='{} items',
msgstr_plural={0: '{} artículo', 1: '{} artículos'},
occurrences=[('items.py', '25')],
comment='Number of items'
)
pofile.append(entry_plural)
# Save the PO file
# For a real application, replace '/tmp/output.po' with a proper path.
# Ensure the directory exists or handle FileNotFoundError.
try:
# Using a temporary file for demonstration purposes
import tempfile
with tempfile.NamedTemporaryFile(suffix='.po', mode='w', delete=False, encoding='utf-8') as f:
temp_po_path = f.name
pofile.save(temp_po_path)
print(f"PO file saved to: {temp_po_path}")
# Optionally compile to MO
temp_mo_path = temp_po_path.replace('.po', '.mo')
pofile.save_as_mofile(temp_mo_path)
print(f"MO file compiled to: {temp_mo_path}")
finally:
# Cleanup temporary files (optional, for real use you'd keep them)
import os
if 'temp_po_path' in locals() and os.path.exists(temp_po_path):
os.remove(temp_po_path)
if 'temp_mo_path' in locals() and os.path.exists(temp_mo_path):
os.remove(temp_mo_path)
# Type checkers will use 'types-polib' to ensure correct usage of polib objects.
# For example, they will verify that 'append' takes a POEntry and 'msgid' is a string.
Debug
Known issues
gotchaThis package provides *only* type stubs. It does not contain any runtime code for `polib` itself. You must install the `polib` library separately for your code to run.fixEnsure both `polib` and `types-polib` are installed: `pip install polib types-polib`.
affects: All
breakingType stubs are version-specific. The `types-polib` version `1.2.0.20260408` is designed to provide accurate annotations for `polib==1.2.*`. Using `types-polib` with significantly different versions of `polib` (e.g., `polib` 0.x or `polib` 2.x if it ever exists) may lead to incorrect type-checking results or errors.fixAlign the `types-polib` version with your installed `polib` version. The `types-polib` version's first three parts typically match the `polib` version it stubs (e.g., `types-polib==1.2.0.*` for `polib==1.2.*`).
affects: All versions where `types-polib` and `polib` major/minor versions mismatch.
gotchaType stubs are consumed by static type checkers (e.g., MyPy, Pyright, PyCharm) at design time. Installing `types-polib` alone will not provide type checking if you are not running a type checker or your IDE is not configured to use them.fixIntegrate a static type checker (e.g., MyPy) into your development workflow. Run `mypy your_module.py` or configure your IDE (e.g., VS Code with Pylance/Pyright) to enable type checking.
affects: All
Upgrade
Version history
1.2.0.20260518latest on PyPI · released May 18, 2026
Audit
Dependencies
polibrequiredRuntime library for which these stubs provide type hints.