django-version-checks 1.16.0

Requirements

Python 3.9 to 3.14 supported.

Django 4.2 to 6.0 supported.

Installation

First, install with pip:

python -m pip install django-version-checks

Second, add the app to your INSTALLED_APPS setting:

INSTALLED_APPS = [
    ...,
    "django_version_checks",
    ...,
]

Third, add a VERSION_CHECKS setting with the version checks you want to enforce (as documented below). For example:

VERSION_CHECKS = {
    "python": "==3.9.*",
}

Usage

See also the introductory blog post.

django-version-checks adds several system checks that can help ensure that the current environment has the right versions of Python, databases, etc. This is useful when coordinating upgrades across all your infrastructure.

Note that django-version-checks does not check the versions of your Python dependencies. This is because mismatched dependency versions are likely to cause ImportErrors or other import-time problems, before system checks run. To version check your Python dependencies, try pip-lock.

Checks use the PEP 440 specifier format via the packaging module. This is the same format used by pip, and allows some flexibility in specifying valid version ranges. The ~= operator is particularly useful. For example, you can use ~=3.9.1 to mean “3.9.1+, but less than 3.10.0”, allowing environments to take on patch releases without changes, but nothing more.

The individual checks are documented below. Each occupies a key in the VERSION_CHECKS dictionary, and documents its supported types for specifiers. If a check is misconfigured with a bad type or specifier you will see one of these system check errors:

• dvc.E001: <check> is misconfigured. Expected a <type> but got <value>.

• dvc.E002: <check> is misconfigured. <value> is not a valid PEP440 specifier.

VERSION_CHECKS = {
    "mysql": "~=10.5.8",
}

VERSION_CHECKS = {
    "postgresql": {
        "default": "~=10.5.8",
        "analytics": "~=10.4.17",
    },
}

VERSION_CHECKS = {
    "postgresql": "~=12.2",
}

VERSION_CHECKS = {
    "postgresql": {
        "default": "~=12.2",
        "analytics": "~=13.1",
    },
}

VERSION_CHECKS = {
    "python": "~=3.9.1",
}

VERSION_CHECKS = {
    "sqlite": "~=3.37",
}

Example Upgrade

Let’s walk through using django-version-checks to upgrade Python from version 3.8 to 3.9. We have an infrastructure consisting of CI, staging, and production environments, and several developers’ development machines.

First, we add a pre-existing check to ensure that all environments are on Python 3.8:

VERSION_CHECKS = {
    "python": "~=3.8.6",
}

Second, we rewrite the specifier to allow versions of Python 3.9:

VERSION_CHECKS = {
    "python": ">=3.8.6,<3.10.0",
}

Third, we upgrade our infrastructure. We’d probably upgrade in the order: CI, development environments, staging, production. Each environment should have an automated run of manage.py check, as per the Django deployment checklist.

Fourth, we change the specifier again to allow Python 3.9 only:

VERSION_CHECKS = {
    "python": "~=3.9.1",
}

And we’re upgraded! 🎉