Fixes the ruff autoup double import

Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.com>

.codecov.yml

@@ -14,10 +14,6 @@ component_management:
 # https://docs.codecov.com/docs/carryforward-flags
 flags:
   # Backend Python versions
-  backend-python-3.10:
-    paths:
-      - src/**
-    carryforward: true
   backend-python-3.11:
     paths:
       - src/**
@@ -26,6 +22,14 @@ flags:
     paths:
       - src/**
     carryforward: true
+  backend-python-3.13:
+    paths:
+      - src/**
+    carryforward: true
+  backend-python-3.14:
+    paths:
+      - src/**
+    carryforward: true
   # Frontend (shards merge into single flag)
   frontend-node-24.x:
     paths:
@@ -41,9 +45,10 @@ coverage:
     project:
       backend:
         flags:
-          - backend-python-3.10
           - backend-python-3.11
           - backend-python-3.12
+          - backend-python-3.13
+          - backend-python-3.14
         paths:
           - src/**
         # https://docs.codecov.com/docs/commit-status#threshold
@@ -59,9 +64,10 @@ coverage:
     patch:
       backend:
         flags:
-          - backend-python-3.10
           - backend-python-3.11
           - backend-python-3.12
+          - backend-python-3.13
+          - backend-python-3.14
         paths:
           - src/**
         target: 100%

.github/workflows/ci-backend.yml

@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-24.04
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
       fail-fast: false
     steps:
       - name: Checkout

CONTRIBUTING.md

@@ -13,7 +13,9 @@ If you want to implement something big:
 
 ## Python
 
-Paperless supports python 3.10 - 3.12 at this time. We format Python code with [ruff](https://docs.astral.sh/ruff/formatter/).
+Paperless-ngx currently supports Python 3.11, 3.12, 3.13, and 3.14. As a policy, we aim to support at least the three most recent Python versions, and drop support for versions as they reach end-of-life. Older versions may be supported if dependencies permit, but this is not guaranteed.
+
+We format Python code with [ruff](https://docs.astral.sh/ruff/formatter/).
 
 ## Branches
 

docs/setup.md

@@ -172,7 +172,7 @@ to enable polling and disable inotify. See [here](configuration.md#polling).
 #### Prerequisites
 
 -   Paperless runs on Linux only, Windows is not supported.
--   Python 3 is required with versions 3.10 - 3.12 currently supported. Newer versions may work, but some dependencies may not be fully compatible.
+-   Python 3.11, 3.12, 3.13, or 3.14 is required. As a policy, Paperless-ngx aims to support at least the three most recent Python versions and drops support for versions as they reach end-of-life. Newer versions may work, but some dependencies may not be fully compatible.
 
 #### Installation
 

pyproject.toml

@@ -3,10 +3,9 @@ name = "paperless-ngx"
 version = "2.20.9"
 description = "A community-supported supercharged document management system: scan, index and archive all your physical documents"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 classifiers = [
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
@@ -177,7 +176,7 @@ torch = [
 ]
 
 [tool.ruff]
-target-version = "py310"
+target-version = "py311"
 line-length = 88
 src = [
   "src",

src-ui/messages.xlf

@@ -1238,8 +1238,8 @@
           <context context-type="linenumber">82</context>
         </context-group>
       </trans-unit>
-      <trans-unit id="8035757452478567832" datatype="html">
-        <source>Update existing document</source>
+      <trans-unit id="7860582931776068318" datatype="html">
+        <source>Add document version</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/components/admin/settings/settings.component.html</context>
           <context context-type="linenumber">280</context>
@@ -8411,8 +8411,8 @@
           <context context-type="linenumber">832</context>
         </context-group>
       </trans-unit>
-      <trans-unit id="6390006284731990222" datatype="html">
-        <source>This operation will permanently rotate the original version of <x id="PH" equiv-text="this.list.selected.size"/> document(s).</source>
+      <trans-unit id="5203024009814367559" datatype="html">
+        <source>This operation will add rotated versions of the <x id="PH" equiv-text="this.list.selected.size"/> document(s).</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/components/document-list/bulk-editor/bulk-editor.component.ts</context>
           <context context-type="linenumber">833</context>

src-ui/src/app/components/admin/settings/settings.component.html

@@ -277,7 +277,7 @@
               <div class="col">
                 <select class="form-select" formControlName="pdfEditorDefaultEditMode">
                   <option [ngValue]="PdfEditorEditMode.Create" i18n>Create new document(s)</option>
-                  <option [ngValue]="PdfEditorEditMode.Update" i18n>Update existing document</option>
+                  <option [ngValue]="PdfEditorEditMode.Update" i18n>Add document version</option>
                 </select>
               </div>
             </div>

src-ui/src/app/components/common/pdf-editor/pdf-editor.component.html

@@ -84,7 +84,7 @@
       <input type="radio" class="btn-check" [(ngModel)]="editMode" [value]="PdfEditorEditMode.Update" id="editModeUpdate" name="editmode" [disabled]="hasSplit()">
       <label for="editModeUpdate" class="btn btn-outline-primary btn-sm">
         <i-bs name="pencil"></i-bs>
-        <span class="form-check-label ms-2" i18n>Update existing document</span>
+        <span class="form-check-label ms-2" i18n>Add document version</span>
       </label>
     </div>
     @if (editMode === PdfEditorEditMode.Create) {

src-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.ts

@@ -830,7 +830,7 @@ export class BulkEditorComponent
     })
     const rotateDialog = modal.componentInstance as RotateConfirmDialogComponent
     rotateDialog.title = $localize`Rotate confirm`
-    rotateDialog.messageBold = $localize`This operation will permanently rotate the original version of ${this.list.selected.size} document(s).`
+    rotateDialog.messageBold = $localize`This operation will add rotated versions of the ${this.list.selected.size} document(s).`
     rotateDialog.btnClass = 'btn-danger'
     rotateDialog.btnCaption = $localize`Proceed`
     rotateDialog.documentID = Array.from(this.list.selected)[0]

src/documents/conditionals.py

@@ -1,5 +1,5 @@
+from datetime import UTC
 from datetime import datetime
-from datetime import timezone
 from typing import Any
 
 from django.conf import settings
@@ -139,7 +139,7 @@ def thumbnail_last_modified(request: Any, pk: int) -> datetime | None:
         # No cache, get the timestamp and cache the datetime
         last_modified = datetime.fromtimestamp(
             doc.thumbnail_path.stat().st_mtime,
-            tz=timezone.utc,
+            tz=UTC,
         )
         cache.set(doc_key, last_modified, CACHE_50_MINUTES)
         return last_modified

src/documents/consumer.py

@@ -2,7 +2,7 @@ import datetime
 import hashlib
 import os
 import tempfile
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import TYPE_CHECKING
 from typing import Final
@@ -81,7 +81,7 @@ class ConsumerError(Exception):
     pass
 
 
-class ConsumerStatusShortMessage(str, Enum):
+class ConsumerStatusShortMessage(StrEnum):
     DOCUMENT_ALREADY_EXISTS = "document_already_exists"
     DOCUMENT_ALREADY_EXISTS_IN_TRASH = "document_already_exists_in_trash"
     ASN_ALREADY_EXISTS = "asn_already_exists"

src/documents/index.py

@@ -5,10 +5,10 @@ import math
 import re
 from collections import Counter
 from contextlib import contextmanager
+from datetime import UTC
 from datetime import datetime
 from datetime import time
 from datetime import timedelta
-from datetime import timezone
 from shutil import rmtree
 from time import sleep
 from typing import TYPE_CHECKING
@@ -437,7 +437,7 @@ class ManualResults:
 class LocalDateParser(English):
     def reverse_timezone_offset(self, d):
         return (d.replace(tzinfo=django_timezone.get_current_timezone())).astimezone(
-            timezone.utc,
+            UTC,
         )
 
     def date_from(self, *args, **kwargs):
@@ -641,8 +641,8 @@ def rewrite_natural_date_keywords(query_string: str) -> str:
                 end = datetime(local_now.year - 1, 12, 31, 23, 59, 59, tzinfo=tz)
 
         # Convert to UTC and format
-        start_str = start.astimezone(timezone.utc).strftime("%Y%m%d%H%M%S")
-        end_str = end.astimezone(timezone.utc).strftime("%Y%m%d%H%M%S")
+        start_str = start.astimezone(UTC).strftime("%Y%m%d%H%M%S")
+        end_str = end.astimezone(UTC).strftime("%Y%m%d%H%M%S")
         return f"{field}:[{start_str} TO {end_str}]"
 
     return re.sub(pattern, repl, query_string, flags=re.IGNORECASE)

src/documents/migrations/0001_squashed.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.7 on 2026-01-15 22:08
+# Generated by Django 5.2.11 on 2026-03-03 16:27
 
 import datetime
 
@@ -21,6 +21,207 @@ class Migration(migrations.Migration):
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
+    replaces = [
+        ("documents", "0001_initial"),
+        ("documents", "0002_auto_20151226_1316"),
+        ("documents", "0003_sender"),
+        ("documents", "0004_auto_20160114_1844"),
+        (
+            "documents",
+            "0004_auto_20160114_1844_squashed_0011_auto_20160303_1929",
+        ),
+        ("documents", "0005_auto_20160123_0313"),
+        ("documents", "0006_auto_20160123_0430"),
+        ("documents", "0007_auto_20160126_2114"),
+        ("documents", "0008_document_file_type"),
+        ("documents", "0009_auto_20160214_0040"),
+        ("documents", "0010_log"),
+        ("documents", "0011_auto_20160303_1929"),
+        ("documents", "0012_auto_20160305_0040"),
+        ("documents", "0013_auto_20160325_2111"),
+        ("documents", "0014_document_checksum"),
+        ("documents", "0015_add_insensitive_to_match"),
+        (
+            "documents",
+            "0015_add_insensitive_to_match_squashed_0018_auto_20170715_1712",
+        ),
+        ("documents", "0016_auto_20170325_1558"),
+        ("documents", "0017_auto_20170512_0507"),
+        ("documents", "0018_auto_20170715_1712"),
+        ("documents", "0019_add_consumer_user"),
+        ("documents", "0020_document_added"),
+        ("documents", "0021_document_storage_type"),
+        ("documents", "0022_auto_20181007_1420"),
+        ("documents", "0023_document_current_filename"),
+        ("documents", "1000_update_paperless_all"),
+        ("documents", "1001_auto_20201109_1636"),
+        ("documents", "1002_auto_20201111_1105"),
+        ("documents", "1003_mime_types"),
+        ("documents", "1004_sanity_check_schedule"),
+        ("documents", "1005_checksums"),
+        ("documents", "1006_auto_20201208_2209"),
+        (
+            "documents",
+            "1006_auto_20201208_2209_squashed_1011_auto_20210101_2340",
+        ),
+        ("documents", "1007_savedview_savedviewfilterrule"),
+        ("documents", "1008_auto_20201216_1736"),
+        ("documents", "1009_auto_20201216_2005"),
+        ("documents", "1010_auto_20210101_2159"),
+        ("documents", "1011_auto_20210101_2340"),
+        ("documents", "1012_fix_archive_files"),
+        ("documents", "1013_migrate_tag_colour"),
+        ("documents", "1014_auto_20210228_1614"),
+        ("documents", "1015_remove_null_characters"),
+        ("documents", "1016_auto_20210317_1351"),
+        (
+            "documents",
+            "1016_auto_20210317_1351_squashed_1020_merge_20220518_1839",
+        ),
+        ("documents", "1017_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1018_alter_savedviewfilterrule_value"),
+        ("documents", "1019_storagepath_document_storage_path"),
+        ("documents", "1019_uisettings"),
+        ("documents", "1020_merge_20220518_1839"),
+        ("documents", "1021_webp_thumbnail_conversion"),
+        ("documents", "1022_paperlesstask"),
+        (
+            "documents",
+            "1022_paperlesstask_squashed_1036_alter_savedviewfilterrule_rule_type",
+        ),
+        ("documents", "1023_add_comments"),
+        ("documents", "1024_document_original_filename"),
+        ("documents", "1025_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1026_transition_to_celery"),
+        (
+            "documents",
+            "1027_remove_paperlesstask_attempted_task_and_more",
+        ),
+        (
+            "documents",
+            "1028_remove_paperlesstask_task_args_and_more",
+        ),
+        ("documents", "1029_alter_document_archive_serial_number"),
+        ("documents", "1030_alter_paperlesstask_task_file_name"),
+        (
+            "documents",
+            "1031_remove_savedview_user_correspondent_owner_and_more",
+        ),
+        (
+            "documents",
+            "1032_alter_correspondent_matching_algorithm_and_more",
+        ),
+        (
+            "documents",
+            "1033_alter_documenttype_options_alter_tag_options_and_more",
+        ),
+        ("documents", "1034_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1035_rename_comment_note"),
+        ("documents", "1036_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1037_webp_encrypted_thumbnail_conversion"),
+        ("documents", "1038_sharelink"),
+        ("documents", "1039_consumptiontemplate"),
+        (
+            "documents",
+            "1040_customfield_customfieldinstance_and_more",
+        ),
+        ("documents", "1041_alter_consumptiontemplate_sources"),
+        (
+            "documents",
+            "1042_consumptiontemplate_assign_custom_fields_and_more",
+        ),
+        ("documents", "1043_alter_savedviewfilterrule_rule_type"),
+        (
+            "documents",
+            "1044_workflow_workflowaction_workflowtrigger_and_more",
+        ),
+        (
+            "documents",
+            "1045_alter_customfieldinstance_value_monetary",
+        ),
+        (
+            "documents",
+            "1045_alter_customfieldinstance_value_monetary_squashed_1049_document_deleted_at_document_restored_at",
+        ),
+        (
+            "documents",
+            "1046_workflowaction_remove_all_correspondents_and_more",
+        ),
+        ("documents", "1047_savedview_display_mode_and_more"),
+        ("documents", "1048_alter_savedviewfilterrule_rule_type"),
+        (
+            "documents",
+            "1049_document_deleted_at_document_restored_at",
+        ),
+        ("documents", "1050_customfield_extra_data_and_more"),
+        (
+            "documents",
+            "1051_alter_correspondent_owner_alter_document_owner_and_more",
+        ),
+        ("documents", "1052_document_transaction_id"),
+        ("documents", "1053_document_page_count"),
+        (
+            "documents",
+            "1054_customfieldinstance_value_monetary_amount_and_more",
+        ),
+        ("documents", "1055_alter_storagepath_path"),
+        (
+            "documents",
+            "1056_customfieldinstance_deleted_at_and_more",
+        ),
+        ("documents", "1057_paperlesstask_owner"),
+        (
+            "documents",
+            "1058_workflowtrigger_schedule_date_custom_field_and_more",
+        ),
+        (
+            "documents",
+            "1059_workflowactionemail_workflowactionwebhook_and_more",
+        ),
+        (
+            "documents",
+            "1060_alter_customfieldinstance_value_select",
+        ),
+        ("documents", "1061_workflowactionwebhook_as_json"),
+        ("documents", "1062_alter_savedviewfilterrule_rule_type"),
+        (
+            "documents",
+            "1063_paperlesstask_type_alter_paperlesstask_task_name_and_more",
+        ),
+        ("documents", "1064_delete_log"),
+        (
+            "documents",
+            "1065_workflowaction_assign_custom_fields_values",
+        ),
+        (
+            "documents",
+            "1066_alter_workflowtrigger_schedule_offset_days",
+        ),
+        ("documents", "1067_alter_document_created"),
+        ("documents", "1068_alter_document_created"),
+        (
+            "documents",
+            "1069_workflowtrigger_filter_has_storage_path_and_more",
+        ),
+        (
+            "documents",
+            "1070_customfieldinstance_value_long_text_and_more",
+        ),
+        (
+            "documents",
+            "1071_tag_tn_ancestors_count_tag_tn_ancestors_pks_and_more",
+        ),
+        (
+            "documents",
+            "1072_workflowtrigger_filter_custom_field_query_and_more",
+        ),
+        ("documents", "1073_migrate_workflow_title_jinja"),
+        (
+            "documents",
+            "1074_workflowrun_deleted_at_workflowrun_restored_at_and_more",
+        ),
+    ]
+
     operations = [
         migrations.CreateModel(
             name="WorkflowActionEmail",
@@ -185,70 +386,6 @@ class Migration(migrations.Migration):
                 "abstract": False,
             },
         ),
-        migrations.CreateModel(
-            name="CustomField",
-            fields=[
-                (
-                    "id",
-                    models.AutoField(
-                        auto_created=True,
-                        primary_key=True,
-                        serialize=False,
-                        verbose_name="ID",
-                    ),
-                ),
-                (
-                    "created",
-                    models.DateTimeField(
-                        db_index=True,
-                        default=django.utils.timezone.now,
-                        editable=False,
-                        verbose_name="created",
-                    ),
-                ),
-                ("name", models.CharField(max_length=128)),
-                (
-                    "data_type",
-                    models.CharField(
-                        choices=[
-                            ("string", "String"),
-                            ("url", "URL"),
-                            ("date", "Date"),
-                            ("boolean", "Boolean"),
-                            ("integer", "Integer"),
-                            ("float", "Float"),
-                            ("monetary", "Monetary"),
-                            ("documentlink", "Document Link"),
-                            ("select", "Select"),
-                            ("longtext", "Long Text"),
-                        ],
-                        editable=False,
-                        max_length=50,
-                        verbose_name="data type",
-                    ),
-                ),
-                (
-                    "extra_data",
-                    models.JSONField(
-                        blank=True,
-                        help_text="Extra data for the custom field, such as select options",
-                        null=True,
-                        verbose_name="extra data",
-                    ),
-                ),
-            ],
-            options={
-                "verbose_name": "custom field",
-                "verbose_name_plural": "custom fields",
-                "ordering": ("created",),
-                "constraints": [
-                    models.UniqueConstraint(
-                        fields=("name",),
-                        name="documents_customfield_unique_name",
-                    ),
-                ],
-            },
-        ),
         migrations.CreateModel(
             name="DocumentType",
             fields=[
@@ -733,17 +870,6 @@ class Migration(migrations.Migration):
                         verbose_name="correspondent",
                     ),
                 ),
-                (
-                    "owner",
-                    models.ForeignKey(
-                        blank=True,
-                        default=None,
-                        null=True,
-                        on_delete=django.db.models.deletion.SET_NULL,
-                        to=settings.AUTH_USER_MODEL,
-                        verbose_name="owner",
-                    ),
-                ),
                 (
                     "document_type",
                     models.ForeignKey(
@@ -767,12 +893,14 @@ class Migration(migrations.Migration):
                     ),
                 ),
                 (
-                    "tags",
-                    models.ManyToManyField(
+                    "owner",
+                    models.ForeignKey(
                         blank=True,
-                        related_name="documents",
-                        to="documents.tag",
-                        verbose_name="tags",
+                        default=None,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        to=settings.AUTH_USER_MODEL,
+                        verbose_name="owner",
                     ),
                 ),
             ],
@@ -782,6 +910,140 @@ class Migration(migrations.Migration):
                 "ordering": ("-created",),
             },
         ),
+        migrations.AddField(
+            model_name="document",
+            name="tags",
+            field=models.ManyToManyField(
+                blank=True,
+                related_name="documents",
+                to="documents.tag",
+                verbose_name="tags",
+            ),
+        ),
+        migrations.CreateModel(
+            name="Note",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("deleted_at", models.DateTimeField(blank=True, null=True)),
+                ("restored_at", models.DateTimeField(blank=True, null=True)),
+                ("transaction_id", models.UUIDField(blank=True, null=True)),
+                (
+                    "note",
+                    models.TextField(
+                        blank=True,
+                        help_text="Note for the document",
+                        verbose_name="content",
+                    ),
+                ),
+                (
+                    "created",
+                    models.DateTimeField(
+                        db_index=True,
+                        default=django.utils.timezone.now,
+                        verbose_name="created",
+                    ),
+                ),
+                (
+                    "document",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notes",
+                        to="documents.document",
+                        verbose_name="document",
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="notes",
+                        to=settings.AUTH_USER_MODEL,
+                        verbose_name="user",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "note",
+                "verbose_name_plural": "notes",
+                "ordering": ("created",),
+            },
+        ),
+        migrations.CreateModel(
+            name="CustomField",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "created",
+                    models.DateTimeField(
+                        db_index=True,
+                        default=django.utils.timezone.now,
+                        editable=False,
+                        verbose_name="created",
+                    ),
+                ),
+                ("name", models.CharField(max_length=128)),
+                (
+                    "data_type",
+                    models.CharField(
+                        choices=[
+                            ("string", "String"),
+                            ("url", "URL"),
+                            ("date", "Date"),
+                            ("boolean", "Boolean"),
+                            ("integer", "Integer"),
+                            ("float", "Float"),
+                            ("monetary", "Monetary"),
+                            ("documentlink", "Document Link"),
+                            ("select", "Select"),
+                            ("longtext", "Long Text"),
+                        ],
+                        editable=False,
+                        max_length=50,
+                        verbose_name="data type",
+                    ),
+                ),
+                (
+                    "extra_data",
+                    models.JSONField(
+                        blank=True,
+                        help_text="Extra data for the custom field, such as select options",
+                        null=True,
+                        verbose_name="extra data",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "custom field",
+                "verbose_name_plural": "custom fields",
+                "ordering": ("created",),
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("name",),
+                        name="documents_customfield_unique_name",
+                    ),
+                ],
+            },
+        ),
         migrations.CreateModel(
             name="CustomFieldInstance",
             fields=[
@@ -880,66 +1142,6 @@ class Migration(migrations.Migration):
                 "ordering": ("created",),
             },
         ),
-        migrations.CreateModel(
-            name="Note",
-            fields=[
-                (
-                    "id",
-                    models.AutoField(
-                        auto_created=True,
-                        primary_key=True,
-                        serialize=False,
-                        verbose_name="ID",
-                    ),
-                ),
-                ("deleted_at", models.DateTimeField(blank=True, null=True)),
-                ("restored_at", models.DateTimeField(blank=True, null=True)),
-                ("transaction_id", models.UUIDField(blank=True, null=True)),
-                (
-                    "note",
-                    models.TextField(
-                        blank=True,
-                        help_text="Note for the document",
-                        verbose_name="content",
-                    ),
-                ),
-                (
-                    "created",
-                    models.DateTimeField(
-                        db_index=True,
-                        default=django.utils.timezone.now,
-                        verbose_name="created",
-                    ),
-                ),
-                (
-                    "document",
-                    models.ForeignKey(
-                        blank=True,
-                        null=True,
-                        on_delete=django.db.models.deletion.CASCADE,
-                        related_name="notes",
-                        to="documents.document",
-                        verbose_name="document",
-                    ),
-                ),
-                (
-                    "user",
-                    models.ForeignKey(
-                        blank=True,
-                        null=True,
-                        on_delete=django.db.models.deletion.SET_NULL,
-                        related_name="notes",
-                        to=settings.AUTH_USER_MODEL,
-                        verbose_name="user",
-                    ),
-                ),
-            ],
-            options={
-                "verbose_name": "note",
-                "verbose_name_plural": "notes",
-                "ordering": ("created",),
-            },
-        ),
         migrations.CreateModel(
             name="PaperlessTask",
             fields=[
@@ -986,7 +1188,6 @@ class Migration(migrations.Migration):
                             ("train_classifier", "Train Classifier"),
                             ("check_sanity", "Check Sanity"),
                             ("index_optimize", "Index Optimize"),
-                            ("llmindex_update", "LLM Index Update"),
                         ],
                         help_text="Name of the task that was run",
                         max_length=255,
@@ -1380,6 +1581,7 @@ class Migration(migrations.Migration):
                         verbose_name="Workflow Action Type",
                     ),
                 ),
+                ("order", models.PositiveIntegerField(default=0, verbose_name="order")),
                 (
                     "assign_title",
                     models.TextField(

src/documents/migrations/0002_squashed.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.9 on 2026-01-20 18:46
+# Generated by Django 5.2.11 on 2026-03-03 16:27
 
 import django.db.models.deletion
 from django.db import migrations
@@ -9,8 +9,14 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("documents", "0001_initial"),
-        ("paperless_mail", "0001_initial"),
+        ("documents", "0001_squashed"),
+        ("paperless_mail", "0001_squashed"),
+    ]
+
+    # This migration needs a "replaces", but it doesn't matter which.
+    # Chose the last 2.20.x migration
+    replaces = [
+        ("documents", "1075_workflowaction_order"),
     ]
 
     operations = [

src/documents/migrations/0003_workflowaction_order.py

@@ -6,7 +6,7 @@ from django.db import models
 
 class Migration(migrations.Migration):
     dependencies = [
-        ("documents", "0002_initial"),
+        ("documents", "0002_squashed"),
     ]
 
     operations = [

src/documents/migrations/0014_alter_paperlesstask_task_name.py

@@ -0,0 +1,30 @@
+# Generated by Django 5.2.11 on 2026-03-03 16:42
+
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("documents", "0013_document_root_document"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="paperlesstask",
+            name="task_name",
+            field=models.CharField(
+                choices=[
+                    ("consume_file", "Consume File"),
+                    ("train_classifier", "Train Classifier"),
+                    ("check_sanity", "Check Sanity"),
+                    ("index_optimize", "Index Optimize"),
+                    ("llmindex_update", "LLM Index Update"),
+                ],
+                help_text="Name of the task that was run",
+                max_length=255,
+                null=True,
+                verbose_name="Task Name",
+            ),
+        ),
+    ]

src/documents/plugins/date_parsing/base.py

@@ -5,11 +5,7 @@ from abc import abstractmethod
 from collections.abc import Iterator
 from dataclasses import dataclass
 from types import TracebackType
-
-try:
-    from typing import Self
-except ImportError:
-    from typing_extensions import Self
+from typing import Self
 
 import dateparser
 

src/documents/plugins/helpers.py

@@ -8,7 +8,7 @@ if TYPE_CHECKING:
     from channels_redis.pubsub import RedisPubSubChannelLayer
 
 
-class ProgressStatusOptions(str, enum.Enum):
+class ProgressStatusOptions(enum.StrEnum):
     STARTED = "STARTED"
     WORKING = "WORKING"
     SUCCESS = "SUCCESS"

src/documents/tests/date_parsing/conftest.py

@@ -24,7 +24,7 @@ def base_config() -> DateParserConfig:
             12,
             0,
             0,
-            tzinfo=datetime.timezone.utc,
+            tzinfo=datetime.UTC,
         ),
         filename_date_order="YMD",
         content_date_order="DMY",
@@ -45,7 +45,7 @@ def config_with_ignore_dates() -> DateParserConfig:
             12,
             0,
             0,
-            tzinfo=datetime.timezone.utc,
+            tzinfo=datetime.UTC,
         ),
         filename_date_order="DMY",
         content_date_order="MDY",

src/documents/tests/date_parsing/test_date_parsing.py

@@ -101,50 +101,50 @@ class TestFilterDate:
         [
             # Valid Dates
             pytest.param(
-                datetime.datetime(2024, 1, 10, tzinfo=datetime.timezone.utc),
-                datetime.datetime(2024, 1, 10, tzinfo=datetime.timezone.utc),
+                datetime.datetime(2024, 1, 10, tzinfo=datetime.UTC),
+                datetime.datetime(2024, 1, 10, tzinfo=datetime.UTC),
                 id="valid_past_date",
             ),
             pytest.param(
-                datetime.datetime(2024, 1, 15, 12, 0, 0, tzinfo=datetime.timezone.utc),
-                datetime.datetime(2024, 1, 15, 12, 0, 0, tzinfo=datetime.timezone.utc),
+                datetime.datetime(2024, 1, 15, 12, 0, 0, tzinfo=datetime.UTC),
+                datetime.datetime(2024, 1, 15, 12, 0, 0, tzinfo=datetime.UTC),
                 id="exactly_at_reference",
             ),
             pytest.param(
-                datetime.datetime(1901, 1, 1, tzinfo=datetime.timezone.utc),
-                datetime.datetime(1901, 1, 1, tzinfo=datetime.timezone.utc),
+                datetime.datetime(1901, 1, 1, tzinfo=datetime.UTC),
+                datetime.datetime(1901, 1, 1, tzinfo=datetime.UTC),
                 id="year_1901_valid",
             ),
             # Date is > reference_time
             pytest.param(
-                datetime.datetime(2024, 1, 16, tzinfo=datetime.timezone.utc),
+                datetime.datetime(2024, 1, 16, tzinfo=datetime.UTC),
                 None,
                 id="future_date_day_after",
             ),
             # date.date() in ignore_dates
             pytest.param(
-                datetime.datetime(2024, 1, 1, 0, 0, 0, tzinfo=datetime.timezone.utc),
+                datetime.datetime(2024, 1, 1, 0, 0, 0, tzinfo=datetime.UTC),
                 None,
                 id="ignored_date_midnight_jan1",
             ),
             pytest.param(
-                datetime.datetime(2024, 1, 1, 10, 30, 0, tzinfo=datetime.timezone.utc),
+                datetime.datetime(2024, 1, 1, 10, 30, 0, tzinfo=datetime.UTC),
                 None,
                 id="ignored_date_midday_jan1",
             ),
             pytest.param(
-                datetime.datetime(2024, 12, 25, 15, 0, 0, tzinfo=datetime.timezone.utc),
+                datetime.datetime(2024, 12, 25, 15, 0, 0, tzinfo=datetime.UTC),
                 None,
                 id="ignored_date_dec25_future",
             ),
             # date.year <= 1900
             pytest.param(
-                datetime.datetime(1899, 12, 31, tzinfo=datetime.timezone.utc),
+                datetime.datetime(1899, 12, 31, tzinfo=datetime.UTC),
                 None,
                 id="year_1899",
             ),
             pytest.param(
-                datetime.datetime(1900, 1, 1, tzinfo=datetime.timezone.utc),
+                datetime.datetime(1900, 1, 1, tzinfo=datetime.UTC),
                 None,
                 id="year_1900_boundary",
             ),
@@ -176,7 +176,7 @@ class TestFilterDate:
             1,
             12,
             0,
-            tzinfo=datetime.timezone.utc,
+            tzinfo=datetime.UTC,
         )
         another_ignored = datetime.datetime(
             2024,
@@ -184,7 +184,7 @@ class TestFilterDate:
             25,
             15,
             30,
-            tzinfo=datetime.timezone.utc,
+            tzinfo=datetime.UTC,
         )
         allowed_date = datetime.datetime(
             2024,
@@ -192,7 +192,7 @@ class TestFilterDate:
             2,
             12,
             0,
-            tzinfo=datetime.timezone.utc,
+            tzinfo=datetime.UTC,
         )
 
         assert parser._filter_date(ignored_date) is None
@@ -204,7 +204,7 @@ class TestFilterDate:
         regex_parser: RegexDateParserPlugin,
     ) -> None:
         """Should work with timezone-aware datetimes."""
-        date_utc = datetime.datetime(2024, 1, 10, 12, 0, tzinfo=datetime.timezone.utc)
+        date_utc = datetime.datetime(2024, 1, 10, 12, 0, tzinfo=datetime.UTC)
 
         result = regex_parser._filter_date(date_utc)
 
@@ -221,8 +221,8 @@ class TestRegexDateParser:
                 "report-2023-12-25.txt",
                 "Event recorded on 25/12/2022.",
                 [
-                    datetime.datetime(2023, 12, 25, tzinfo=datetime.timezone.utc),
-                    datetime.datetime(2022, 12, 25, tzinfo=datetime.timezone.utc),
+                    datetime.datetime(2023, 12, 25, tzinfo=datetime.UTC),
+                    datetime.datetime(2022, 12, 25, tzinfo=datetime.UTC),
                 ],
                 id="filename-y-m-d_and_content-d-m-y",
             ),
@@ -230,8 +230,8 @@ class TestRegexDateParser:
                 "img_2023.01.02.jpg",
                 "Taken on 01/02/2023",
                 [
-                    datetime.datetime(2023, 1, 2, tzinfo=datetime.timezone.utc),
-                    datetime.datetime(2023, 2, 1, tzinfo=datetime.timezone.utc),
+                    datetime.datetime(2023, 1, 2, tzinfo=datetime.UTC),
+                    datetime.datetime(2023, 2, 1, tzinfo=datetime.UTC),
                 ],
                 id="ambiguous-dates-respect-orders",
             ),
@@ -239,7 +239,7 @@ class TestRegexDateParser:
                 "notes.txt",
                 "bad date 99/99/9999 and 25/12/2022",
                 [
-                    datetime.datetime(2022, 12, 25, tzinfo=datetime.timezone.utc),
+                    datetime.datetime(2022, 12, 25, tzinfo=datetime.UTC),
                 ],
                 id="parse-exception-skips-bad-and-yields-good",
             ),
@@ -275,24 +275,24 @@ class TestRegexDateParser:
                 or "2023.12.25" in date_string
                 or "2023-12-25" in date_string
             ):
-                return datetime.datetime(2023, 12, 25, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2023, 12, 25, tzinfo=datetime.UTC)
 
             # content DMY 25/12/2022
             if "25/12/2022" in date_string or "25-12-2022" in date_string:
-                return datetime.datetime(2022, 12, 25, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2022, 12, 25, tzinfo=datetime.UTC)
 
             # filename YMD 2023.01.02
             if "2023.01.02" in date_string or "2023-01-02" in date_string:
-                return datetime.datetime(2023, 1, 2, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2023, 1, 2, tzinfo=datetime.UTC)
 
             # ambiguous 01/02/2023 -> respect DATE_ORDER setting
             if "01/02/2023" in date_string:
                 if date_order == "DMY":
-                    return datetime.datetime(2023, 2, 1, tzinfo=datetime.timezone.utc)
+                    return datetime.datetime(2023, 2, 1, tzinfo=datetime.UTC)
                 if date_order == "YMD":
-                    return datetime.datetime(2023, 1, 2, tzinfo=datetime.timezone.utc)
+                    return datetime.datetime(2023, 1, 2, tzinfo=datetime.UTC)
                 # fallback
-                return datetime.datetime(2023, 2, 1, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2023, 2, 1, tzinfo=datetime.UTC)
 
             # simulate parse failure for malformed input
             if "99/99/9999" in date_string or "bad date" in date_string:
@@ -328,7 +328,7 @@ class TestRegexDateParser:
                 12,
                 0,
                 0,
-                tzinfo=datetime.timezone.utc,
+                tzinfo=datetime.UTC,
             ),
             filename_date_order="YMD",
             content_date_order="DMY",
@@ -344,13 +344,13 @@ class TestRegexDateParser:
         ) -> datetime.datetime | None:
             if "10/12/2023" in date_string or "10-12-2023" in date_string:
                 # ignored date
-                return datetime.datetime(2023, 12, 10, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2023, 12, 10, tzinfo=datetime.UTC)
             if "01/02/2024" in date_string or "01-02-2024" in date_string:
                 # future relative to reference_time -> filtered
-                return datetime.datetime(2024, 2, 1, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2024, 2, 1, tzinfo=datetime.UTC)
             if "05/01/2023" in date_string or "05-01-2023" in date_string:
                 # valid
-                return datetime.datetime(2023, 1, 5, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2023, 1, 5, tzinfo=datetime.UTC)
             return None
 
         mocker.patch(target, side_effect=fake_parse)
@@ -358,7 +358,7 @@ class TestRegexDateParser:
         content = "Ignored: 10/12/2023, Future: 01/02/2024, Keep: 05/01/2023"
         results = list(parser.parse("whatever.txt", content))
 
-        assert results == [datetime.datetime(2023, 1, 5, tzinfo=datetime.timezone.utc)]
+        assert results == [datetime.datetime(2023, 1, 5, tzinfo=datetime.UTC)]
 
     def test_parse_handles_no_matches_and_returns_empty_list(
         self,
@@ -392,7 +392,7 @@ class TestRegexDateParser:
                 12,
                 0,
                 0,
-                tzinfo=datetime.timezone.utc,
+                tzinfo=datetime.UTC,
             ),
             filename_date_order=None,
             content_date_order="DMY",
@@ -409,9 +409,9 @@ class TestRegexDateParser:
         ) -> datetime.datetime | None:
             # return distinct datetimes so we can tell which source was parsed
             if "25/12/2022" in date_string:
-                return datetime.datetime(2022, 12, 25, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2022, 12, 25, tzinfo=datetime.UTC)
             if "2023-12-25" in date_string:
-                return datetime.datetime(2023, 12, 25, tzinfo=datetime.timezone.utc)
+                return datetime.datetime(2023, 12, 25, tzinfo=datetime.UTC)
             return None
 
         mock = mocker.patch(target, side_effect=fake_parse)
@@ -429,5 +429,5 @@ class TestRegexDateParser:
         assert "25/12/2022" in called_date_string
         # And the parser should have yielded the corresponding datetime
         assert results == [
-            datetime.datetime(2022, 12, 25, tzinfo=datetime.timezone.utc),
+            datetime.datetime(2022, 12, 25, tzinfo=datetime.UTC),
         ]

src/documents/tests/test_file_handling.py

@@ -336,7 +336,11 @@ class TestFileHandling(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
             added=d1,
         )
 
-        self.assertEqual(generate_filename(doc1), Path("1232-01-09.pdf"))
+        # Account for 3.14 padding changes
+        expected_year: str = d1.strftime("%Y")
+        expected_filename: Path = Path(f"{expected_year}-01-09.pdf")
+
+        self.assertEqual(generate_filename(doc1), expected_filename)
 
         doc1.added = timezone.make_aware(datetime.datetime(2020, 11, 16, 1, 1, 1))
 

src/documents/tests/test_filters.py

@@ -21,7 +21,7 @@ class TestDateLocalization:
         14,
         30,
         5,
-        tzinfo=datetime.timezone.utc,
+        tzinfo=datetime.UTC,
     )
 
     TEST_DATETIME_STRING: str = "2023-10-26T14:30:05+00:00"

src/documents/tests/test_workflows.py

@@ -4666,7 +4666,7 @@ class TestDateWorkflowLocalization(
         14,
         30,
         5,
-        tzinfo=datetime.timezone.utc,
+        tzinfo=datetime.UTC,
     )
 
     @pytest.mark.parametrize(

src/documents/versioning.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from enum import Enum
+from enum import StrEnum
 from typing import TYPE_CHECKING
 from typing import Any
 
@@ -11,7 +11,7 @@ if TYPE_CHECKING:
     from django.http import HttpRequest
 
 
-class VersionResolutionError(str, Enum):
+class VersionResolutionError(StrEnum):
     INVALID = "invalid"
     NOT_FOUND = "not_found"
 

src/paperless/checks.py

@@ -204,6 +204,61 @@ def audit_log_check(app_configs, **kwargs):
     return result
 
 
+@register()
+def check_v3_minimum_upgrade_version(
+    app_configs: object,
+    **kwargs: object,
+) -> list[Error]:
+    """Enforce that upgrades to v3 must start from v2.20.9.
+
+    v3 squashes all prior migrations into 0001_squashed and 0002_squashed.
+    If a user skips v2.20.9, the data migration in 1075_workflowaction_order
+    never runs and the squash may apply schema changes against an incomplete
+    database state.
+    """
+    from django.db import DatabaseError
+    from django.db import OperationalError
+
+    try:
+        all_tables = connections["default"].introspection.table_names()
+
+        if "django_migrations" not in all_tables:
+            return []
+
+        with connections["default"].cursor() as cursor:
+            cursor.execute(
+                "SELECT name FROM django_migrations WHERE app = %s",
+                ["documents"],
+            )
+            applied: set[str] = {row[0] for row in cursor.fetchall()}
+
+        if not applied:
+            return []
+
+        # Already in a valid v3 state
+        if {"0001_squashed", "0002_squashed"} & applied:
+            return []
+
+        # On v2.20.9 exactly — squash will pick up cleanly from here
+        if "1075_workflowaction_order" in applied:
+            return []
+
+    except (DatabaseError, OperationalError):
+        return []
+
+    return [
+        Error(
+            "Cannot upgrade to Paperless-ngx v3 from this version.",
+            hint=(
+                "Upgrading to v3 can only be performed from v2.20.9."
+                "Please upgrade to v2.20.9, run migrations, then upgrade to v3."
+                "See https://docs.paperless-ngx.com/setup/#upgrading for details."
+            ),
+            id="paperless.E002",
+        ),
+    ]
+
+
 @register()
 def check_deprecated_db_settings(
     app_configs: object,

src/paperless/tests/test_adapter.py

@@ -1,100 +1,107 @@
-import logging
+from unittest import mock
 
-import pytest
 from allauth.account.adapter import get_adapter
 from allauth.core import context
 from allauth.socialaccount.adapter import get_adapter as get_social_adapter
+from django.conf import settings
 from django.contrib.auth.models import AnonymousUser
 from django.contrib.auth.models import Group
 from django.contrib.auth.models import User
 from django.forms import ValidationError
 from django.http import HttpRequest
+from django.test import TestCase
+from django.test import override_settings
 from django.urls import reverse
-from pytest_django.fixtures import SettingsWrapper
-from pytest_mock import MockerFixture
 from rest_framework.authtoken.models import Token
 
 from paperless.adapter import DrfTokenStrategy
 
 
-@pytest.mark.django_db
-class TestCustomAccountAdapter:
-    def test_is_open_for_signup(self, settings: SettingsWrapper) -> None:
+class TestCustomAccountAdapter(TestCase):
+    def test_is_open_for_signup(self) -> None:
         adapter = get_adapter()
 
         # With no accounts, signups should be allowed
-        assert adapter.is_open_for_signup(None)
+        self.assertTrue(adapter.is_open_for_signup(None))
 
         User.objects.create_user("testuser")
 
+        # Test when ACCOUNT_ALLOW_SIGNUPS is True
         settings.ACCOUNT_ALLOW_SIGNUPS = True
-        assert adapter.is_open_for_signup(None)
+        self.assertTrue(adapter.is_open_for_signup(None))
 
+        # Test when ACCOUNT_ALLOW_SIGNUPS is False
         settings.ACCOUNT_ALLOW_SIGNUPS = False
-        assert not adapter.is_open_for_signup(None)
+        self.assertFalse(adapter.is_open_for_signup(None))
 
-    def test_is_safe_url(self, settings: SettingsWrapper) -> None:
+    def test_is_safe_url(self) -> None:
         request = HttpRequest()
-        request.get_host = lambda: "example.com"
+        request.get_host = mock.Mock(return_value="example.com")
         with context.request_context(request):
             adapter = get_adapter()
+            with override_settings(ALLOWED_HOSTS=["*"]):
+                # True because request host is same
+                url = "https://example.com"
+                self.assertTrue(adapter.is_safe_url(url))
 
-            settings.ALLOWED_HOSTS = ["*"]
-            # True because request host is same
-            assert adapter.is_safe_url("https://example.com")
+            url = "https://evil.com"
             # False despite wildcard because request host is different
-            assert not adapter.is_safe_url("https://evil.com")
+            self.assertFalse(adapter.is_safe_url(url))
 
             settings.ALLOWED_HOSTS = ["example.com"]
+            url = "https://example.com"
             # True because request host is same
-            assert adapter.is_safe_url("https://example.com")
+            self.assertTrue(adapter.is_safe_url(url))
 
             settings.ALLOWED_HOSTS = ["*", "example.com"]
+            url = "//evil.com"
             # False because request host is not in allowed hosts
-            assert not adapter.is_safe_url("//evil.com")
+            self.assertFalse(adapter.is_safe_url(url))
 
-    def test_pre_authenticate(
-        self,
-        settings: SettingsWrapper,
-        mocker: MockerFixture,
-    ) -> None:
-        mocker.patch("allauth.core.internal.ratelimit.consume", return_value=True)
+    @mock.patch("allauth.core.internal.ratelimit.consume", return_value=True)
+    def test_pre_authenticate(self, mock_consume) -> None:
         adapter = get_adapter()
         request = HttpRequest()
-        request.get_host = lambda: "example.com"
+        request.get_host = mock.Mock(return_value="example.com")
 
         settings.DISABLE_REGULAR_LOGIN = False
         adapter.pre_authenticate(request)
 
         settings.DISABLE_REGULAR_LOGIN = True
-        with pytest.raises(ValidationError):
+        with self.assertRaises(ValidationError):
             adapter.pre_authenticate(request)
 
-    def test_get_reset_password_from_key_url(self, settings: SettingsWrapper) -> None:
+    def test_get_reset_password_from_key_url(self) -> None:
         request = HttpRequest()
-        request.get_host = lambda: "foo.org"
+        request.get_host = mock.Mock(return_value="foo.org")
         with context.request_context(request):
             adapter = get_adapter()
 
-            settings.PAPERLESS_URL = None
-            settings.ACCOUNT_DEFAULT_HTTP_PROTOCOL = "https"
-            expected_url = f"https://foo.org{reverse('account_reset_password_from_key', kwargs={'uidb36': 'UID', 'key': 'KEY'})}"
-            assert adapter.get_reset_password_from_key_url("UID-KEY") == expected_url
+            # Test when PAPERLESS_URL is None
+            with override_settings(
+                PAPERLESS_URL=None,
+                ACCOUNT_DEFAULT_HTTP_PROTOCOL="https",
+            ):
+                expected_url = f"https://foo.org{reverse('account_reset_password_from_key', kwargs={'uidb36': 'UID', 'key': 'KEY'})}"
+                self.assertEqual(
+                    adapter.get_reset_password_from_key_url("UID-KEY"),
+                    expected_url,
+                )
 
-            settings.PAPERLESS_URL = "https://bar.com"
-            expected_url = f"https://bar.com{reverse('account_reset_password_from_key', kwargs={'uidb36': 'UID', 'key': 'KEY'})}"
-            assert adapter.get_reset_password_from_key_url("UID-KEY") == expected_url
+            # Test when PAPERLESS_URL is not None
+            with override_settings(PAPERLESS_URL="https://bar.com"):
+                expected_url = f"https://bar.com{reverse('account_reset_password_from_key', kwargs={'uidb36': 'UID', 'key': 'KEY'})}"
+                self.assertEqual(
+                    adapter.get_reset_password_from_key_url("UID-KEY"),
+                    expected_url,
+                )
 
-    def test_save_user_adds_groups(
-        self,
-        settings: SettingsWrapper,
-        mocker: MockerFixture,
-    ) -> None:
-        settings.ACCOUNT_DEFAULT_GROUPS = ["group1", "group2"]
+    @override_settings(ACCOUNT_DEFAULT_GROUPS=["group1", "group2"])
+    def test_save_user_adds_groups(self) -> None:
         Group.objects.create(name="group1")
         user = User.objects.create_user("testuser")
         adapter = get_adapter()
-        form = mocker.MagicMock(
+        form = mock.Mock(
             cleaned_data={
                 "username": "testuser",
                 "email": "user@example.com",
@@ -103,81 +110,88 @@ class TestCustomAccountAdapter:
 
         user = adapter.save_user(HttpRequest(), user, form, commit=True)
 
-        assert user.groups.count() == 1
-        assert user.groups.filter(name="group1").exists()
-        assert not user.groups.filter(name="group2").exists()
+        self.assertEqual(user.groups.count(), 1)
+        self.assertTrue(user.groups.filter(name="group1").exists())
+        self.assertFalse(user.groups.filter(name="group2").exists())
 
-    def test_fresh_install_save_creates_superuser(self, mocker: MockerFixture) -> None:
+    def test_fresh_install_save_creates_superuser(self) -> None:
         adapter = get_adapter()
-        form = mocker.MagicMock(
+        form = mock.Mock(
             cleaned_data={
                 "username": "testuser",
                 "email": "user@paperless-ngx.com",
             },
         )
         user = adapter.save_user(HttpRequest(), User(), form, commit=True)
-        assert user.is_superuser
+        self.assertTrue(user.is_superuser)
 
-        form = mocker.MagicMock(
+        # Next time, it should not create a superuser
+        form = mock.Mock(
             cleaned_data={
                 "username": "testuser2",
                 "email": "user2@paperless-ngx.com",
             },
         )
         user2 = adapter.save_user(HttpRequest(), User(), form, commit=True)
-        assert not user2.is_superuser
+        self.assertFalse(user2.is_superuser)
 
 
-class TestCustomSocialAccountAdapter:
-    @pytest.mark.django_db
-    def test_is_open_for_signup(self, settings: SettingsWrapper) -> None:
+class TestCustomSocialAccountAdapter(TestCase):
+    def test_is_open_for_signup(self) -> None:
         adapter = get_social_adapter()
 
+        # Test when SOCIALACCOUNT_ALLOW_SIGNUPS is True
         settings.SOCIALACCOUNT_ALLOW_SIGNUPS = True
-        assert adapter.is_open_for_signup(None, None)
+        self.assertTrue(adapter.is_open_for_signup(None, None))
 
+        # Test when SOCIALACCOUNT_ALLOW_SIGNUPS is False
         settings.SOCIALACCOUNT_ALLOW_SIGNUPS = False
-        assert not adapter.is_open_for_signup(None, None)
+        self.assertFalse(adapter.is_open_for_signup(None, None))
 
     def test_get_connect_redirect_url(self) -> None:
         adapter = get_social_adapter()
-        assert adapter.get_connect_redirect_url(None, None) == reverse("base")
+        request = None
+        socialaccount = None
 
-    @pytest.mark.django_db
-    def test_save_user_adds_groups(
-        self,
-        settings: SettingsWrapper,
-        mocker: MockerFixture,
-    ) -> None:
-        settings.SOCIAL_ACCOUNT_DEFAULT_GROUPS = ["group1", "group2"]
+        # Test the default URL
+        expected_url = reverse("base")
+        self.assertEqual(
+            adapter.get_connect_redirect_url(request, socialaccount),
+            expected_url,
+        )
+
+    @override_settings(SOCIAL_ACCOUNT_DEFAULT_GROUPS=["group1", "group2"])
+    def test_save_user_adds_groups(self) -> None:
         Group.objects.create(name="group1")
         adapter = get_social_adapter()
+        request = HttpRequest()
         user = User.objects.create_user("testuser")
-        sociallogin = mocker.MagicMock(user=user)
+        sociallogin = mock.Mock(
+            user=user,
+        )
 
-        user = adapter.save_user(HttpRequest(), sociallogin, None)
+        user = adapter.save_user(request, sociallogin, None)
 
-        assert user.groups.count() == 1
-        assert user.groups.filter(name="group1").exists()
-        assert not user.groups.filter(name="group2").exists()
+        self.assertEqual(user.groups.count(), 1)
+        self.assertTrue(user.groups.filter(name="group1").exists())
+        self.assertFalse(user.groups.filter(name="group2").exists())
 
-    def test_error_logged_on_authentication_error(
-        self,
-        caplog: pytest.LogCaptureFixture,
-    ) -> None:
+    def test_error_logged_on_authentication_error(self) -> None:
         adapter = get_social_adapter()
-        with caplog.at_level(logging.INFO, logger="paperless.auth"):
+        request = HttpRequest()
+        with self.assertLogs("paperless.auth", level="INFO") as log_cm:
             adapter.on_authentication_error(
-                HttpRequest(),
+                request,
                 provider="test-provider",
                 error="Error",
                 exception="Test authentication error",
             )
-        assert any("Test authentication error" in msg for msg in caplog.messages)
+        self.assertTrue(
+            any("Test authentication error" in message for message in log_cm.output),
+        )
 
 
-@pytest.mark.django_db
-class TestDrfTokenStrategy:
+class TestDrfTokenStrategy(TestCase):
     def test_create_access_token_creates_new_token(self) -> None:
         """
         GIVEN:
@@ -187,6 +201,7 @@ class TestDrfTokenStrategy:
         THEN:
             - A new token is created and its key is returned
         """
+
         user = User.objects.create_user("testuser")
         request = HttpRequest()
         request.user = user
@@ -194,9 +209,13 @@ class TestDrfTokenStrategy:
         strategy = DrfTokenStrategy()
         token_key = strategy.create_access_token(request)
 
-        assert token_key is not None
-        assert Token.objects.filter(user=user).exists()
-        assert token_key == Token.objects.get(user=user).key
+        # Verify a token was created
+        self.assertIsNotNone(token_key)
+        self.assertTrue(Token.objects.filter(user=user).exists())
+
+        # Verify the returned key matches the created token
+        token = Token.objects.get(user=user)
+        self.assertEqual(token_key, token.key)
 
     def test_create_access_token_returns_existing_token(self) -> None:
         """
@@ -207,6 +226,7 @@ class TestDrfTokenStrategy:
         THEN:
             - The same token key is returned (no new token created)
         """
+
         user = User.objects.create_user("testuser")
         existing_token = Token.objects.create(user=user)
 
@@ -216,8 +236,11 @@ class TestDrfTokenStrategy:
         strategy = DrfTokenStrategy()
         token_key = strategy.create_access_token(request)
 
-        assert token_key == existing_token.key
-        assert Token.objects.filter(user=user).count() == 1
+        # Verify the existing token key is returned
+        self.assertEqual(token_key, existing_token.key)
+
+        # Verify only one token exists (no duplicate created)
+        self.assertEqual(Token.objects.filter(user=user).count(), 1)
 
     def test_create_access_token_returns_none_for_unauthenticated_user(self) -> None:
         """
@@ -228,11 +251,12 @@ class TestDrfTokenStrategy:
         THEN:
             - None is returned and no token is created
         """
+
         request = HttpRequest()
         request.user = AnonymousUser()
 
         strategy = DrfTokenStrategy()
         token_key = strategy.create_access_token(request)
 
-        assert token_key is None
-        assert Token.objects.count() == 0
+        self.assertIsNone(token_key)
+        self.assertEqual(Token.objects.count(), 0)

src/paperless/tests/test_checks.py

@@ -1,98 +1,73 @@
 import os
-from dataclasses import dataclass
 from pathlib import Path
+from unittest import mock
 
 import pytest
+from django.core.checks import Error
 from django.core.checks import Warning
-from pytest_django.fixtures import SettingsWrapper
+from django.test import TestCase
+from django.test import override_settings
 from pytest_mock import MockerFixture
 
+from documents.tests.utils import DirectoriesMixin
+from documents.tests.utils import FileSystemAssertsMixin
 from paperless.checks import audit_log_check
 from paperless.checks import binaries_check
 from paperless.checks import check_deprecated_db_settings
+from paperless.checks import check_v3_minimum_upgrade_version
 from paperless.checks import debug_mode_check
 from paperless.checks import paths_check
 from paperless.checks import settings_values_check
 
 
-@dataclass(frozen=True, slots=True)
-class PaperlessTestDirs:
-    data_dir: Path
-    media_dir: Path
-    consumption_dir: Path
-
-
-# TODO: consolidate with documents/tests/conftest.py PaperlessDirs/paperless_dirs
-#       once the paperless and documents test suites are ready to share fixtures.
-@pytest.fixture()
-def directories(tmp_path: Path, settings: SettingsWrapper) -> PaperlessTestDirs:
-    data_dir = tmp_path / "data"
-    media_dir = tmp_path / "media"
-    consumption_dir = tmp_path / "consumption"
-
-    for d in (data_dir, media_dir, consumption_dir):
-        d.mkdir()
-
-    settings.DATA_DIR = data_dir
-    settings.MEDIA_ROOT = media_dir
-    settings.CONSUMPTION_DIR = consumption_dir
-
-    return PaperlessTestDirs(
-        data_dir=data_dir,
-        media_dir=media_dir,
-        consumption_dir=consumption_dir,
-    )
-
-
-class TestChecks:
+class TestChecks(DirectoriesMixin, TestCase):
     def test_binaries(self) -> None:
-        assert binaries_check(None) == []
+        self.assertEqual(binaries_check(None), [])
 
-    def test_binaries_fail(self, settings: SettingsWrapper) -> None:
-        settings.CONVERT_BINARY = "uuuhh"
-        assert len(binaries_check(None)) == 1
+    @override_settings(CONVERT_BINARY="uuuhh")
+    def test_binaries_fail(self) -> None:
+        self.assertEqual(len(binaries_check(None)), 1)
 
-    @pytest.mark.usefixtures("directories")
     def test_paths_check(self) -> None:
-        assert paths_check(None) == []
+        self.assertEqual(paths_check(None), [])
 
-    def test_paths_check_dont_exist(self, settings: SettingsWrapper) -> None:
-        settings.MEDIA_ROOT = Path("uuh")
-        settings.DATA_DIR = Path("whatever")
-        settings.CONSUMPTION_DIR = Path("idontcare")
+    @override_settings(
+        MEDIA_ROOT=Path("uuh"),
+        DATA_DIR=Path("whatever"),
+        CONSUMPTION_DIR=Path("idontcare"),
+    )
+    def test_paths_check_dont_exist(self) -> None:
+        msgs = paths_check(None)
+        self.assertEqual(len(msgs), 3, str(msgs))
+
+        for msg in msgs:
+            self.assertTrue(msg.msg.endswith("is set but doesn't exist."))
+
+    def test_paths_check_no_access(self) -> None:
+        Path(self.dirs.data_dir).chmod(0o000)
+        Path(self.dirs.media_dir).chmod(0o000)
+        Path(self.dirs.consumption_dir).chmod(0o000)
+
+        self.addCleanup(os.chmod, self.dirs.data_dir, 0o777)
+        self.addCleanup(os.chmod, self.dirs.media_dir, 0o777)
+        self.addCleanup(os.chmod, self.dirs.consumption_dir, 0o777)
 
         msgs = paths_check(None)
+        self.assertEqual(len(msgs), 3)
 
-        assert len(msgs) == 3, str(msgs)
         for msg in msgs:
-            assert msg.msg.endswith("is set but doesn't exist.")
+            self.assertTrue(msg.msg.endswith("is not writeable"))
 
-    def test_paths_check_no_access(self, directories: PaperlessTestDirs) -> None:
-        directories.data_dir.chmod(0o000)
-        directories.media_dir.chmod(0o000)
-        directories.consumption_dir.chmod(0o000)
+    @override_settings(DEBUG=False)
+    def test_debug_disabled(self) -> None:
+        self.assertEqual(debug_mode_check(None), [])
 
-        try:
-            msgs = paths_check(None)
-        finally:
-            directories.data_dir.chmod(0o777)
-            directories.media_dir.chmod(0o777)
-            directories.consumption_dir.chmod(0o777)
-
-        assert len(msgs) == 3
-        for msg in msgs:
-            assert msg.msg.endswith("is not writeable")
-
-    def test_debug_disabled(self, settings: SettingsWrapper) -> None:
-        settings.DEBUG = False
-        assert debug_mode_check(None) == []
-
-    def test_debug_enabled(self, settings: SettingsWrapper) -> None:
-        settings.DEBUG = True
-        assert len(debug_mode_check(None)) == 1
+    @override_settings(DEBUG=True)
+    def test_debug_enabled(self) -> None:
+        self.assertEqual(len(debug_mode_check(None)), 1)
 
 
-class TestSettingsChecksAgainstDefaults:
+class TestSettingsChecksAgainstDefaults(DirectoriesMixin, TestCase):
     def test_all_valid(self) -> None:
         """
         GIVEN:
@@ -103,71 +78,104 @@ class TestSettingsChecksAgainstDefaults:
             - No system check errors reported
         """
         msgs = settings_values_check(None)
-        assert len(msgs) == 0
+        self.assertEqual(len(msgs), 0)
 
 
-class TestOcrSettingsChecks:
-    @pytest.mark.parametrize(
-        ("setting", "value", "expected_msg"),
-        [
-            pytest.param(
-                "OCR_OUTPUT_TYPE",
-                "notapdf",
-                'OCR output type "notapdf"',
-                id="invalid-output-type",
-            ),
-            pytest.param(
-                "OCR_MODE",
-                "makeitso",
-                'OCR output mode "makeitso"',
-                id="invalid-mode",
-            ),
-            pytest.param(
-                "OCR_MODE",
-                "skip_noarchive",
-                "deprecated",
-                id="deprecated-mode",
-            ),
-            pytest.param(
-                "OCR_SKIP_ARCHIVE_FILE",
-                "invalid",
-                'OCR_SKIP_ARCHIVE_FILE setting "invalid"',
-                id="invalid-skip-archive-file",
-            ),
-            pytest.param(
-                "OCR_CLEAN",
-                "cleanme",
-                'OCR clean mode "cleanme"',
-                id="invalid-clean",
-            ),
-        ],
-    )
-    def test_invalid_setting_produces_one_error(
-        self,
-        settings: SettingsWrapper,
-        setting: str,
-        value: str,
-        expected_msg: str,
-    ) -> None:
+class TestOcrSettingsChecks(DirectoriesMixin, TestCase):
+    @override_settings(OCR_OUTPUT_TYPE="notapdf")
+    def test_invalid_output_type(self) -> None:
         """
         GIVEN:
             - Default settings
-            - One OCR setting is set to an invalid value
+            - OCR output type is invalid
         WHEN:
             - Settings are validated
         THEN:
-            - Exactly one system check error is reported containing the expected message
+            - system check error reported for OCR output type
         """
-        setattr(settings, setting, value)
-
         msgs = settings_values_check(None)
+        self.assertEqual(len(msgs), 1)
 
-        assert len(msgs) == 1
-        assert expected_msg in msgs[0].msg
+        msg = msgs[0]
+
+        self.assertIn('OCR output type "notapdf"', msg.msg)
+
+    @override_settings(OCR_MODE="makeitso")
+    def test_invalid_ocr_type(self) -> None:
+        """
+        GIVEN:
+            - Default settings
+            - OCR type is invalid
+        WHEN:
+            - Settings are validated
+        THEN:
+            - system check error reported for OCR type
+        """
+        msgs = settings_values_check(None)
+        self.assertEqual(len(msgs), 1)
+
+        msg = msgs[0]
+
+        self.assertIn('OCR output mode "makeitso"', msg.msg)
+
+    @override_settings(OCR_MODE="skip_noarchive")
+    def test_deprecated_ocr_type(self) -> None:
+        """
+        GIVEN:
+            - Default settings
+            - OCR type is deprecated
+        WHEN:
+            - Settings are validated
+        THEN:
+            - deprecation warning reported for OCR type
+        """
+        msgs = settings_values_check(None)
+        self.assertEqual(len(msgs), 1)
+
+        msg = msgs[0]
+
+        self.assertIn("deprecated", msg.msg)
+
+    @override_settings(OCR_SKIP_ARCHIVE_FILE="invalid")
+    def test_invalid_ocr_skip_archive_file(self) -> None:
+        """
+        GIVEN:
+            - Default settings
+            - OCR_SKIP_ARCHIVE_FILE is invalid
+        WHEN:
+            - Settings are validated
+        THEN:
+            - system check error reported for OCR_SKIP_ARCHIVE_FILE
+        """
+        msgs = settings_values_check(None)
+        self.assertEqual(len(msgs), 1)
+
+        msg = msgs[0]
+
+        self.assertIn('OCR_SKIP_ARCHIVE_FILE setting "invalid"', msg.msg)
+
+    @override_settings(OCR_CLEAN="cleanme")
+    def test_invalid_ocr_clean(self) -> None:
+        """
+        GIVEN:
+            - Default settings
+            - OCR cleaning type is invalid
+        WHEN:
+            - Settings are validated
+        THEN:
+            - system check error reported for OCR cleaning type
+        """
+        msgs = settings_values_check(None)
+        self.assertEqual(len(msgs), 1)
+
+        msg = msgs[0]
+
+        self.assertIn('OCR clean mode "cleanme"', msg.msg)
 
 
-class TestTimezoneSettingsChecks:
-    def test_invalid_timezone(self, settings: SettingsWrapper) -> None:
+class TestTimezoneSettingsChecks(DirectoriesMixin, TestCase):
+    @override_settings(TIME_ZONE="TheMoon\\MyCrater")
+    def test_invalid_timezone(self) -> None:
         """
         GIVEN:
             - Default settings
@@ -177,16 +185,17 @@ class TestTimezoneSettingsChecks:
         THEN:
             - system check error reported for timezone
         """
-        settings.TIME_ZONE = "TheMoon\\MyCrater"
-
         msgs = settings_values_check(None)
+        self.assertEqual(len(msgs), 1)
 
-        assert len(msgs) == 1
-        assert 'Timezone "TheMoon\\MyCrater"' in msgs[0].msg
+        msg = msgs[0]
+
+        self.assertIn('Timezone "TheMoon\\MyCrater"', msg.msg)
 
 
-class TestEmailCertSettingsChecks:
-    def test_not_valid_file(self, settings: SettingsWrapper) -> None:
+class TestEmailCertSettingsChecks(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
+    @override_settings(EMAIL_CERTIFICATE_FILE=Path("/tmp/not_actually_here.pem"))
+    def test_not_valid_file(self) -> None:
         """
         GIVEN:
             - Default settings
@@ -196,22 +205,19 @@ class TestEmailCertSettingsChecks:
         THEN:
             - system check error reported for email certificate
         """
-        cert_path = Path("/tmp/not_actually_here.pem")
-        assert not cert_path.is_file()
-        settings.EMAIL_CERTIFICATE_FILE = cert_path
+        self.assertIsNotFile("/tmp/not_actually_here.pem")
 
         msgs = settings_values_check(None)
 
-        assert len(msgs) == 1
-        assert "Email cert /tmp/not_actually_here.pem is not a file" in msgs[0].msg
+        self.assertEqual(len(msgs), 1)
+
+        msg = msgs[0]
+
+        self.assertIn("Email cert /tmp/not_actually_here.pem is not a file", msg.msg)
 
 
-class TestAuditLogChecks:
-    def test_was_enabled_once(
-        self,
-        settings: SettingsWrapper,
-        mocker: MockerFixture,
-    ) -> None:
+class TestAuditLogChecks(TestCase):
+    def test_was_enabled_once(self) -> None:
         """
         GIVEN:
             - Audit log is not enabled
@@ -220,18 +226,23 @@ class TestAuditLogChecks:
         THEN:
             - system check error reported for disabling audit log
         """
-        settings.AUDIT_LOG_ENABLED = False
-        introspect_mock = mocker.MagicMock()
+        introspect_mock = mock.MagicMock()
         introspect_mock.introspection.table_names.return_value = ["auditlog_logentry"]
-        mocker.patch.dict(
-            "paperless.checks.connections",
-            {"default": introspect_mock},
-        )
+        with override_settings(AUDIT_LOG_ENABLED=False):
+            with mock.patch.dict(
+                "paperless.checks.connections",
+                {"default": introspect_mock},
+            ):
+                msgs = audit_log_check(None)
 
-        msgs = audit_log_check(None)
+                self.assertEqual(len(msgs), 1)
 
-        assert len(msgs) == 1
-        assert "auditlog table was found but audit log is disabled." in msgs[0].msg
+                msg = msgs[0]
+
+                self.assertIn(
+                    ("auditlog table was found but audit log is disabled."),
+                    msg.msg,
+                )
 
 
 DEPRECATED_VARS: dict[str, str] = {
@@ -260,16 +271,20 @@ class TestDeprecatedDbSettings:
     @pytest.mark.parametrize(
         ("env_var", "db_option_key"),
         [
-            pytest.param("PAPERLESS_DB_TIMEOUT", "timeout", id="db-timeout"),
-            pytest.param(
-                "PAPERLESS_DB_POOLSIZE",
-                "pool.min_size / pool.max_size",
-                id="db-poolsize",
-            ),
-            pytest.param("PAPERLESS_DBSSLMODE", "sslmode", id="ssl-mode"),
-            pytest.param("PAPERLESS_DBSSLROOTCERT", "sslrootcert", id="ssl-rootcert"),
-            pytest.param("PAPERLESS_DBSSLCERT", "sslcert", id="ssl-cert"),
-            pytest.param("PAPERLESS_DBSSLKEY", "sslkey", id="ssl-key"),
+            ("PAPERLESS_DB_TIMEOUT", "timeout"),
+            ("PAPERLESS_DB_POOLSIZE", "pool.min_size / pool.max_size"),
+            ("PAPERLESS_DBSSLMODE", "sslmode"),
+            ("PAPERLESS_DBSSLROOTCERT", "sslrootcert"),
+            ("PAPERLESS_DBSSLCERT", "sslcert"),
+            ("PAPERLESS_DBSSLKEY", "sslkey"),
+        ],
+        ids=[
+            "db-timeout",
+            "db-poolsize",
+            "ssl-mode",
+            "ssl-rootcert",
+            "ssl-cert",
+            "ssl-key",
         ],
     )
     def test_single_deprecated_var_produces_one_warning(
@@ -382,3 +397,240 @@ class TestDeprecatedDbSettings:
 
         assert len(result) == 1
         assert "PAPERLESS_DBSSLCERT" in result[0].msg
+
+
+class TestV3MinimumUpgradeVersionCheck:
+    """Test suite for check_v3_minimum_upgrade_version system check."""
+
+    @pytest.fixture
+    def build_conn_mock(self, mocker: MockerFixture):
+        """Factory fixture that builds a connections['default'] mock.
+
+        Usage::
+
+            conn = build_conn_mock(tables=["django_migrations"], applied=["1075_..."])
+        """
+
+        def _build(tables: list[str], applied: list[str]) -> mock.MagicMock:
+            conn = mocker.MagicMock()
+            conn.introspection.table_names.return_value = tables
+            cursor = conn.cursor.return_value.__enter__.return_value
+            cursor.fetchall.return_value = [(name,) for name in applied]
+            return conn
+
+        return _build
+
+    def test_no_migrations_table_fresh_install(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - No django_migrations table exists in the database
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (fresh install, nothing to enforce)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock([], [])},
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_no_documents_migrations_fresh_install(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - django_migrations table exists but has no documents app rows
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (fresh install, nothing to enforce)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock(["django_migrations"], [])},
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v3_state_with_0001_squashed(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - 0001_squashed is recorded in django_migrations
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (DB is already in a valid v3 state)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    ["0001_squashed", "0002_squashed", "0003_workflowaction_order"],
+                ),
+            },
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v3_state_with_0002_squashed_only(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - Only 0002_squashed is recorded in django_migrations
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (0002_squashed alone confirms a valid v3 state)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock(["django_migrations"], ["0002_squashed"])},
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v2_20_9_state_ready_to_upgrade(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - 1075_workflowaction_order (the last v2.20.9 migration) is in the DB
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (squash will pick up cleanly from this state)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    [
+                        "1074_workflowrun_deleted_at_workflowrun_restored_at_and_more",
+                        "1075_workflowaction_order",
+                    ],
+                ),
+            },
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v2_20_8_raises_error(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - 1074 (last v2.20.8 migration) is applied but 1075 is not
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - An Error with id paperless.E002 is returned
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    ["1074_workflowrun_deleted_at_workflowrun_restored_at_and_more"],
+                ),
+            },
+        )
+        result = check_v3_minimum_upgrade_version(None)
+        assert len(result) == 1
+        assert isinstance(result[0], Error)
+        assert result[0].id == "paperless.E002"
+
+    def test_very_old_version_raises_error(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - Only old migrations (well below v2.20.9) are applied
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - An Error with id paperless.E002 is returned
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    ["1000_update_paperless_all", "1022_paperlesstask"],
+                ),
+            },
+        )
+        result = check_v3_minimum_upgrade_version(None)
+        assert len(result) == 1
+        assert isinstance(result[0], Error)
+        assert result[0].id == "paperless.E002"
+
+    def test_error_hint_mentions_v2_20_9(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - DB is on an old v2 version (pre-v2.20.9)
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - The error hint explicitly references v2.20.9 so users know what to do
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock(["django_migrations"], ["1022_paperlesstask"])},
+        )
+        result = check_v3_minimum_upgrade_version(None)
+        assert len(result) == 1
+        assert "v2.20.9" in result[0].hint
+
+    def test_db_error_is_swallowed(self, mocker: MockerFixture) -> None:
+        """
+        GIVEN:
+            - A DatabaseError is raised when querying the DB
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No exception propagates and an empty list is returned
+        """
+        from django.db import DatabaseError
+
+        conn = mocker.MagicMock()
+        conn.introspection.table_names.side_effect = DatabaseError("connection refused")
+        mocker.patch.dict("paperless.checks.connections", {"default": conn})
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_operational_error_is_swallowed(self, mocker: MockerFixture) -> None:
+        """
+        GIVEN:
+            - An OperationalError is raised when querying the DB
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No exception propagates and an empty list is returned
+        """
+        from django.db import OperationalError
+
+        conn = mocker.MagicMock()
+        conn.introspection.table_names.side_effect = OperationalError("DB unavailable")
+        mocker.patch.dict("paperless.checks.connections", {"default": conn})
+        assert check_v3_minimum_upgrade_version(None) == []

src/paperless/tests/test_utils.py

@@ -9,50 +9,35 @@ from paperless.utils import ocr_to_dateparser_languages
 @pytest.mark.parametrize(
     ("ocr_language", "expected"),
     [
-        pytest.param("eng", ["en"], id="single-language"),
-        pytest.param("fra+ita+lao", ["fr", "it", "lo"], id="multiple-languages"),
-        pytest.param("fil", ["fil"], id="no-two-letter-equivalent"),
-        pytest.param(
-            "aze_cyrl+srp_latn",
-            ["az-Cyrl", "sr-Latn"],
-            id="script-supported-by-dateparser",
-        ),
-        pytest.param(
-            "deu_frak",
-            ["de"],
-            id="script-not-supported-falls-back-to-language",
-        ),
-        pytest.param(
-            "chi_tra+chi_sim",
-            ["zh"],
-            id="chinese-variants-collapse-to-general",
-        ),
-        pytest.param(
-            "eng+unsupported_language+por",
-            ["en", "pt"],
-            id="unsupported-language-skipped",
-        ),
-        pytest.param(
-            "unsupported1+unsupported2",
-            [],
-            id="all-unsupported-returns-empty",
-        ),
-        pytest.param("eng+eng", ["en"], id="duplicates-deduplicated"),
-        pytest.param(
-            "ita_unknownscript",
-            ["it"],
-            id="unknown-script-falls-back-to-language",
-        ),
+        # One language
+        ("eng", ["en"]),
+        # Multiple languages
+        ("fra+ita+lao", ["fr", "it", "lo"]),
+        # Languages that don't have a two-letter equivalent
+        ("fil", ["fil"]),
+        # Languages with a script part supported by dateparser
+        ("aze_cyrl+srp_latn", ["az-Cyrl", "sr-Latn"]),
+        # Languages with a script part not supported by dateparser
+        # In this case, default to the language without script
+        ("deu_frak", ["de"]),
+        # Traditional and simplified chinese don't have the same name in dateparser,
+        # so they're converted to the general chinese language
+        ("chi_tra+chi_sim", ["zh"]),
+        # If a language is not supported by dateparser, fallback to the supported ones
+        ("eng+unsupported_language+por", ["en", "pt"]),
+        # If no language is supported, fallback to default
+        ("unsupported1+unsupported2", []),
+        # Duplicate languages, should not duplicate in result
+        ("eng+eng", ["en"]),
+        # Language with script, but script is not mapped
+        ("ita_unknownscript", ["it"]),
     ],
 )
-def test_ocr_to_dateparser_languages(ocr_language: str, expected: list[str]) -> None:
+def test_ocr_to_dateparser_languages(ocr_language, expected):
     assert sorted(ocr_to_dateparser_languages(ocr_language)) == sorted(expected)
 
 
-def test_ocr_to_dateparser_languages_exception(
-    monkeypatch: pytest.MonkeyPatch,
-    caplog: pytest.LogCaptureFixture,
-) -> None:
+def test_ocr_to_dateparser_languages_exception(monkeypatch, caplog):
     # Patch LocaleDataLoader.get_locale_map to raise an exception
     class DummyLoader:
         def get_locale_map(self, locales=None):

src/paperless/tests/test_views.py

@@ -1,31 +1,24 @@
+import tempfile
 from pathlib import Path
 
-from django.test import Client
-from pytest_django.fixtures import SettingsWrapper
+from django.test import override_settings
 
 
-def test_favicon_view(
-    client: Client,
-    tmp_path: Path,
-    settings: SettingsWrapper,
-) -> None:
-    favicon_path = tmp_path / "paperless" / "img" / "favicon.ico"
-    favicon_path.parent.mkdir(parents=True)
-    favicon_path.write_bytes(b"FAKE ICON DATA")
+def test_favicon_view(client):
+    with tempfile.TemporaryDirectory() as tmpdir:
+        static_dir = Path(tmpdir)
+        favicon_path = static_dir / "paperless" / "img" / "favicon.ico"
+        favicon_path.parent.mkdir(parents=True, exist_ok=True)
+        favicon_path.write_bytes(b"FAKE ICON DATA")
 
-    settings.STATIC_ROOT = tmp_path
-
-    response = client.get("/favicon.ico")
-    assert response.status_code == 200
-    assert response["Content-Type"] == "image/x-icon"
-    assert b"".join(response.streaming_content) == b"FAKE ICON DATA"
+        with override_settings(STATIC_ROOT=static_dir):
+            response = client.get("/favicon.ico")
+            assert response.status_code == 200
+            assert response["Content-Type"] == "image/x-icon"
+            assert b"".join(response.streaming_content) == b"FAKE ICON DATA"
 
 
-def test_favicon_view_missing_file(
-    client: Client,
-    tmp_path: Path,
-    settings: SettingsWrapper,
-) -> None:
-    settings.STATIC_ROOT = tmp_path
-    response = client.get("/favicon.ico")
-    assert response.status_code == 404
+def test_favicon_view_missing_file(client):
+    with override_settings(STATIC_ROOT=Path(tempfile.mkdtemp())):
+        response = client.get("/favicon.ico")
+        assert response.status_code == 404

src/paperless_mail/migrations/0001_squashed.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.9 on 2026-01-20 18:46
+# Generated by Django 5.2.11 on 2026-03-03 16:27
 
 import django.db.models.deletion
 import django.utils.timezone
@@ -15,6 +15,50 @@ class Migration(migrations.Migration):
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
+    replaces = [
+        ("paperless_mail", "0001_initial"),
+        ("paperless_mail", "0001_initial_squashed_0009_mailrule_assign_tags"),
+        ("paperless_mail", "0002_auto_20201117_1334"),
+        ("paperless_mail", "0003_auto_20201118_1940"),
+        ("paperless_mail", "0004_mailrule_order"),
+        ("paperless_mail", "0005_help_texts"),
+        ("paperless_mail", "0006_auto_20210101_2340"),
+        ("paperless_mail", "0007_auto_20210106_0138"),
+        ("paperless_mail", "0008_auto_20210516_0940"),
+        ("paperless_mail", "0009_alter_mailrule_action_alter_mailrule_folder"),
+        ("paperless_mail", "0009_mailrule_assign_tags"),
+        ("paperless_mail", "0010_auto_20220311_1602"),
+        ("paperless_mail", "0011_remove_mailrule_assign_tag"),
+        (
+            "paperless_mail",
+            "0011_remove_mailrule_assign_tag_squashed_0024_alter_mailrule_name_and_more",
+        ),
+        ("paperless_mail", "0012_alter_mailrule_assign_tags"),
+        ("paperless_mail", "0013_merge_20220412_1051"),
+        ("paperless_mail", "0014_alter_mailrule_action"),
+        ("paperless_mail", "0015_alter_mailrule_action"),
+        ("paperless_mail", "0016_mailrule_consumption_scope"),
+        ("paperless_mail", "0017_mailaccount_owner_mailrule_owner"),
+        ("paperless_mail", "0018_processedmail"),
+        ("paperless_mail", "0019_mailrule_filter_to"),
+        ("paperless_mail", "0020_mailaccount_is_token"),
+        ("paperless_mail", "0021_alter_mailaccount_password"),
+        ("paperless_mail", "0022_mailrule_assign_owner_from_rule_and_more"),
+        ("paperless_mail", "0023_remove_mailrule_filter_attachment_filename_and_more"),
+        ("paperless_mail", "0024_alter_mailrule_name_and_more"),
+        (
+            "paperless_mail",
+            "0025_alter_mailaccount_owner_alter_mailrule_owner_and_more",
+        ),
+        ("paperless_mail", "0026_mailrule_enabled"),
+        (
+            "paperless_mail",
+            "0027_mailaccount_expiration_mailaccount_account_type_and_more",
+        ),
+        ("paperless_mail", "0028_alter_mailaccount_password_and_more"),
+        ("paperless_mail", "0029_mailrule_pdf_layout"),
+    ]
+
     operations = [
         migrations.CreateModel(
             name="MailAccount",

src/paperless_mail/migrations/0002_optimize_integer_field_sizes.py

@@ -6,7 +6,7 @@ from django.db import models
 
 class Migration(migrations.Migration):
     dependencies = [
-        ("paperless_mail", "0001_initial"),
+        ("paperless_mail", "0001_squashed"),
     ]
 
     operations = [