Install & Compatibility
Where this runs
tested against v? · pip install
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
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseCheck
✓ from weblate.checks.base import BaseCheck
Common import for defining custom translation checks within Weblate.
BaseAddon
✓ from weblate.addons.base import BaseAddon
Common import for defining custom add-ons to extend Weblate's functionality.
messages
✓ from weblate.trans.models import TranslationEntry as messages
✗ from weblate.trans.messages import Message
The core translation entry model was moved/renamed. Direct access is often via 'TranslationEntry'.
This quickstart demonstrates how to define a custom translation check for Weblate. Weblate is a Django application, and its 'library' usage primarily involves extending its functionality (e.g., custom checks, add-ons) by importing its base classes. This code is not standalone runnable but serves as an example of an extension you would integrate into a running Weblate instance by configuring it in `settings.py`.
import os
from weblate.checks.base import BaseCheck
from weblate.checks.base import CheckResult, WARNING
# This example defines a custom Weblate check.
# To run it, you would add it to your Weblate configuration (settings.py).
# It is not directly executable as a standalone script outside a Weblate instance.
class MyCustomLengthCheck(BaseCheck):
# Unique ID for the check
check_id = 'my-custom-length-check'
# Human-readable name
name = 'Too Long Translation Check'
# Description for the user interface
description = 'Checks if a translation exceeds a maximum allowed length.'
# Default parameters, configurable via Weblate UI
params = {'max_length': 50}
def check(self, check_context):
translation = check_context.translation
source = check_context.source_string
if translation and translation.text and source and source.text:
max_len = self.get_param('max_length')
if len(translation.text) > max_len:
yield CheckResult(
start=0,
end=len(translation.text),
severity=WARNING,
message=f'Translation is too long ({len(translation.text)} chars), max allowed is {max_len} chars.'
)
# Example of how you *might* register it (typically done in settings.py):
# WLB_CHECKS = {'my-custom-length-check': 'my_module.my_custom_check.MyCustomLengthCheck'}
print("Custom check 'MyCustomLengthCheck' defined. Register it in your Weblate settings.py to use it.")
Debug
Known issues
breakingWeblate has strict Python version requirements. Version 5.17 (and generally 5.2+) requires Python 3.12 or newer. Older versions required Python 3.10/3.11. Ensure your environment matches.fixUpgrade your Python environment to 3.12+ before installing or upgrading Weblate 5.2+. Check Weblate's release notes for specific version compatibility.
affects: 5.2.x onwards
breakingWeblate's major versions are often tied to specific Django versions. Upgrading Weblate without ensuring Django compatibility can lead to `django.core.exceptions.ImproperlyConfigured` or migration failures.fixAlways consult Weblate's official documentation and release notes for the required Django version for your specific Weblate release. For Weblate 5.17, Django >=4.2,<5.2 is required.
affects: All major versions, especially 5.x
gotchaThere are two distinct Python packages: `weblate` (the server application) and `weblate_api` (a client library for Weblate's API). Do not confuse them; `weblate` provides the server, while `weblate_api` is used by *other* Python applications to interact with a running Weblate instance.fixUse `pip install weblate` to set up the Weblate server. Use `pip install weblate_api` in *separate* projects if you want to programmatically interact with a Weblate API. Do not try to import API client functionality directly from the `weblate` package.
affects: All
gotchaDatabase migrations are critical for Weblate upgrades. Skipping them or running them incorrectly can corrupt your translation data.fixAlways run `weblate migrate` (or `django-admin migrate` in a Weblate context) after upgrading Weblate, and always back up your database before performing major upgrades.
affects: All versions on upgrade
Upgrade
Version history
2026.6.1latest on PyPI · released Jun 1, 2026
Audit
Dependencies
DjangorequiredWeblate is a Django application and requires a compatible Django version (>=4.2,<5.2 for Weblate 5.17).
CeleryrequiredUsed for background tasks and asynchronous operations.
weblate_apioptionalThis is a separate Python client library for interacting with Weblate's REST API. Not required for running Weblate itself, but essential for programmatic access from external scripts.