### Start Paperless-ngx Backend Development Servers

Source: https://docs.paperless-ngx.com/development

Starts the Django development server, the document consumer, and the Celery worker. These are essential components for running the Paperless-ngx backend during development.

```bash
# src/

$ python3 manage.py runserver & \
  python3 manage.py document_consumer & \
  celery --app paperless worker -l DEBUG

```

--------------------------------

### Build Front-end for Production

Source: https://docs.paperless-ngx.com/development

Installs front-end dependencies using pnpm and builds the front-end application for production using Angular CLI. This is required if you need to test backend changes that interact with the UI.

```bash
# src-ui/

$ pnpm install
$ ng build --configuration production

```

--------------------------------

### Install Python Development Dependencies

Source: https://docs.paperless-ngx.com/development

Installs the development dependencies for the Python backend using 'uv sync'. This command ensures all necessary libraries for development are present.

```bash
$ uv sync --group dev

```

--------------------------------

### Install Pre-commit Hooks

Source: https://docs.paperless-ngx.com/development

Installs the pre-commit hooks for the project. These hooks automate code formatting and linting before commits, ensuring code consistency.

```bash
$ uv run pre-commit install

```

--------------------------------

### Start Paperless-ngx Webserver with Granian

Source: https://docs.paperless-ngx.com/usage

Starts the paperless-ngx webserver using Granian, an ASGI application server. This command is used to serve the administration pages, API, and frontend. Ensure you are in the correct directory before execution.

```shell
cd /path/to/paperless/src/ 
granian --interface asginl --ws "paperless.asgi:application"
```

--------------------------------

### Run Redis Container

Source: https://docs.paperless-ngx.com/development

Starts a Redis instance in a Docker container. Redis is often used as a message broker or cache for applications like Paperless-ngx.

```bash
docker run -d -p 6379:6379 --restart unless-stopped redis:latest

```

--------------------------------

### Setup AngularJS Frontend Development Environment

Source: https://docs.paperless-ngx.com/development

Steps to set up the front-end development environment using Node.js, pnpm, and the Angular CLI. Requires Node.js (version 14.15+) and pnpm. Commands are executed in the `src-ui` directory.

```bash
pnpm install -g @angular/cli
```

```bash
pnpm install
```

```bash
ng serve
```

--------------------------------

### Serve Documentation Locally with MkDocs

Source: https://docs.paperless-ngx.com/development

Command to serve the project's documentation locally with MkDocs. This provides a live-reloading server for previewing documentation changes at http://127.0.0.1:8000.

```shell
$ uv run mkdocs serve
```

--------------------------------

### Start Paperless-ngx Document Consumer

Source: https://docs.paperless-ngx.com/usage

Starts the paperless-ngx document consumer service using the management command `document_consumer`. This service monitors the consumption folder for new documents. Navigate to the source directory before running this command.

```shell
cd /path/to/paperless/src/ 
python3 manage.py document_consumer
```

--------------------------------

### Build Frontend for Production

Source: https://docs.paperless-ngx.com/development

Command to build the frontend for production. The output is placed in a location served by the Django server as static content, useful for verifying authentication.

```bash
$ ng build --configuration production
```

--------------------------------

### Create Consume and Media Directories

Source: https://docs.paperless-ngx.com/development

Creates the necessary 'consume' and 'media' directories for Paperless-ngx to operate. These directories are essential for storing documents and media files.

```bash
mkdir -p consume media

```

--------------------------------

### Start Paperless-ngx Docker Compose

Source: https://docs.paperless-ngx.com/setup

This command starts the Paperless-ngx instance in detached mode using Docker Compose. It ensures that Paperless-ngx runs in the background and will automatically start on system boot.

```bash
docker compose up -d
```

--------------------------------

### Build Documentation with MkDocs

Source: https://docs.paperless-ngx.com/development

Command to build the project's documentation locally using MkDocs. This command utilizes a specific configuration file for the build process.

```shell
$ uv run mkdocs build --config-file mkdocs.yml
```

--------------------------------

### Custom Container Initialization in Docker Compose

Source: https://docs.paperless-ngx.com/advanced_usage

Configures Docker Compose to mount a directory containing custom initialization scripts into the container's `/custom-cont-init.d` directory. These scripts are executed at startup, allowing for custom setup like installing additional packages.

```yaml
services:
    # ...
    webserver:
        # ...
        volumes:
            - /path/to/my/scripts:/custom-cont-init.d:ro
```

--------------------------------

### Install Paperless-ngx System Dependencies (Debian/Buster)

Source: https://docs.paperless-ngx.com/setup

Installs essential system packages required for Paperless-ngx, including Python, image processing tools, and database connectors. These are fundamental for core functionality and document handling.

```bash
sudo apt update && sudo apt install -y python3 python3-pip python3-dev imagemagick fonts-liberation gnupg libpq-dev default-libmysqlclient-dev pkg-config libmagic-dev libzbar0 poppler-utils
```

--------------------------------

### Install Python Requirements for Paperless-ngx

Source: https://docs.paperless-ngx.com/setup

This command installs all the necessary Python dependencies for Paperless-ngx from the requirements.txt file. It ensures that the application has all the libraries it needs to run.

```bash
sudo -Hu paperless pip3 install -r requirements.txt
```

--------------------------------

### Paperless-ngx Configuration Example (Redis)

Source: https://docs.paperless-ngx.com/setup

Illustrates a basic configuration setting for Paperless-ngx, specifically pointing to the Redis server. Ensure the `PAPERLESS_REDIS` value matches your Redis instance.

```ini
PAPERLESS_REDIS="redis://localhost:6379/"

```

--------------------------------

### Installing Tesseract OCR Language Pack (Debian/Ubuntu)

Source: https://docs.paperless-ngx.com/troubleshooting

Installs the Spanish language pack for Tesseract OCR on Debian or Ubuntu systems. This is necessary when OCR accuracy is low for documents in a specific language, and the consumer warns about OCR failures.

```shell
apt-get install -y tesseract-ocr-spa

```

--------------------------------

### Manually Invoking Paperless Task Processor

Source: https://docs.paperless-ngx.com/troubleshooting

This command manually starts the celery task processor for Paperless-ngx. It is used when the task processor is not running automatically, typically in non-Docker setups. Ensure you are in the correct directory where Paperless is installed.

```shell
celery --app paperless worker

```

--------------------------------

### Install Raspberry Pi Specific Dependencies for Paperless-ngx

Source: https://docs.paperless-ngx.com/setup

Installs additional libraries required for Paperless-ngx on Raspberry Pi systems, such as those for scientific computing and XML processing. Also includes build tools for Python dependencies.

```bash
sudo apt install -y libatlas-base-dev libxslt1-dev mime-support build-essential python3-setuptools python3-wheel
```

--------------------------------

### Paperless-ngx Configuration Example (Database)

Source: https://docs.paperless-ngx.com/setup

Shows how to configure Paperless-ngx to use different database backends like PostgreSQL, MariaDB, or SQLite. Includes settings for hostname, port, database name, user, and password.

```ini
PAPERLESS_DBENGINE="postgres"
PAPERLESS_DBHOST="localhost:5432"
PAPERLESS_DBNAME="paperless"
PAPERLESS_DBUSER="paperless"
PAPERLESS_DBPASS="paperless_password"

```

--------------------------------

### Web-UI Loading Stuck (Shell/Static Assets)

Source: https://docs.paperless-ngx.com/troubleshooting

Troubleshoots the Paperless-ngx Web-UI getting stuck at 'Loading...'. This can be caused by missing static frontend files. Ensure that `collectstatic` has been executed successfully, either manually or during the Docker image build, and that frontend assets are compiled and present in the expected directories.

```shell
# Ensure you are in the paperless-ngx source directory or the relevant Docker volume
# Run collectstatic if you built the image yourself or deployed manually
python manage.py collectstatic --noinput

# If deploying via Docker, ensure the build process includes collectstatic
# Example Dockerfile snippet:
# RUN python manage.py collectstatic --noinput

# Verify frontend compilation (if building from source)
# Check for files in src/documents/static/frontend/<lang-code>/

```

--------------------------------

### Install OCR Dependencies for Paperless-ngx

Source: https://docs.paperless-ngx.com/setup

Installs packages necessary for OCRmyPDF, enabling text recognition within documents. This includes tools for PDF processing, image optimization, and the Tesseract OCR engine with language packs.

```bash
sudo apt install -y unpaper ghostscript icc-profiles-free qpdf liblept5 libxml2 pngquant zlib1g tesseract-ocr tesseract-ocr-eng tesseract-ocr-deu
```

--------------------------------

### Extract Paperless-ngx Release Archive

Source: https://docs.paperless-ngx.com/setup

Extracts the downloaded Paperless-ngx release archive using the tar command. This prepares the source files for installation.

```bash
tar -xf paperless-ngx-v1.10.2.tar.xz
```

--------------------------------

### Build Docker Image Locally

Source: https://docs.paperless-ngx.com/development

Command to build and tag a Docker image for Paperless-ngx locally. This is useful for faster development cycles compared to relying solely on GitHub Actions.

```shell
docker build --file Dockerfile --tag paperless:local .
```

--------------------------------

### Shell Script Permission Example

Source: https://docs.paperless-ngx.com/advanced_usage

Provides an example of how to set execute permissions on a shell script, which is often necessary for scripts run via Docker or directly. This command ensures the script can be executed by the system.

```bash
sudo chmod 755 post-consumption-example.sh
```

--------------------------------

### Apply Django Migrations and Create Superuser

Source: https://docs.paperless-ngx.com/development

Applies database migrations and creates a superuser account for the Django application. This is crucial for initializing the database schema and user management.

```bash
# src/

$ uv run manage.py migrate
$ uv run manage.py createsuperuser

```

--------------------------------

### Paperless-ngx Configuration Example (Directories)

Source: https://docs.paperless-ngx.com/setup

Defines essential directories for Paperless-ngx, including where it watches for new documents (`PAPERLESS_CONSUMPTION_DIR`), stores its data (`PAPERLESS_DATA_DIR`), and manages media files (`PAPERLESS_MEDIA_ROOT`).

```ini
PAPERLESS_CONSUMPTION_DIR="/path/to/consumption"
PAPERLESS_DATA_DIR="/opt/paperless/data"
PAPERLESS_MEDIA_ROOT="/opt/paperless/media"

```

--------------------------------

### Search Autocomplete API Endpoint

Source: https://docs.paperless-ngx.com/api

Example of using the `/api/search/autocomplete/` endpoint to get search term suggestions. Requires a `term` query parameter and optionally a `limit`.

```http
/api/search/autocomplete/?term=your_partial_term&limit=10
```

--------------------------------

### Run Paperless-ngx Development Server

Source: https://docs.paperless-ngx.com/setup

This command manually starts the Paperless-ngx development web server. It is useful for testing the application locally but should not be used in production due to security and performance limitations.

```bash
# Manually starts the webserver
sudo -Hu paperless python3 manage.py runserver
```

--------------------------------

### Configure Social Account SSO Providers (JSON Example)

Source: https://docs.paperless-ngx.com/configuration

Defines social account providers compatible with django-allauth for authentication and signup. Requires additional Django applications in PAPERLESS_APPS. The example shows configuration for OpenID Connect, including scopes necessary for group synchronization.

```json
PAPERLESS_SOCIALACCOUNT_PROVIDERS='{
    "openid_connect": {
        "SCOPE": ["openid", "profile", "email", "groups"]
    }
}'
```

--------------------------------

### Manage Packages with uv

Source: https://docs.paperless-ngx.com/development

Commands for managing packages and virtual environments using `uv`. This includes upgrading all locked packages, upgrading a specific package, and adding new packages for development or general use.

```bash
uv lock --upgrade
```

```bash
uv lock --upgrade-package <package>
```

```bash
uv add <package>
```

```bash
uv add --dev <package>
```

--------------------------------

### Run Backend Tests

Source: https://docs.paperless-ngx.com/development

Executes all backend tests using pytest in the 'src/' directory. This command also generates an HTML coverage report, helping to identify areas of the code that are not sufficiently tested.

```bash
pytest

```

--------------------------------

### Example Filename Templates

Source: https://docs.paperless-ngx.com/advanced_usage

Demonstrates how to use placeholders to define custom filename structures for document storage. These templates can include document metadata and dates.

```template
By Year = {{ created_year }}/{{ correspondent }}/{{ title }}
Insurances = Insurances/{{ correspondent }}/{{ created_year }}-{{ created_month }}-{{ created_day }} {{ title }}
```

--------------------------------

### Post-consumption Script Example: Log Document Details

Source: https://docs.paperless-ngx.com/advanced_usage

This bash script provides an example of a post-consumption hook. It logs detailed information about the consumed document, including its ID, filename, type, and associated metadata, to standard output. This script is useful for auditing or integrating with external systems after a document has been successfully processed by Paperless-ngx.

```bash
#!/usr/bin/env bash

echo "
A document with an id of ${DOCUMENT_ID} was just consumed.  I know the
following additional information about it:

* Generated File Name: ${DOCUMENT_FILE_NAME}
* Document type: ${DOCUMENT_TYPE}
* Archive Path: ${DOCUMENT_ARCHIVE_PATH}
* Source Path: ${DOCUMENT_SOURCE_PATH}
* Created: ${DOCUMENT_CREATED}
* Added: ${DOCUMENT_ADDED}
* Modified: ${DOCUMENT_MODIFIED}
* Thumbnail Path: ${DOCUMENT_THUMBNAIL_PATH}
* Download URL: ${DOCUMENT_DOWNLOAD_URL}
* Thumbnail URL: ${DOCUMENT_THUMBNAIL_URL}
* Owner Name: ${DOCUMENT_OWNER}
* Correspondent: ${DOCUMENT_CORRESPONDENT}
* Tags: ${DOCUMENT_TAGS}

It was consumed with the passphrase ${PASSPHRASE}

"

```

--------------------------------

### Paperless-ngx Configuration Example (OCR and Timezone)

Source: https://docs.paperless-ngx.com/setup

Configures the OCR language for text recognition and the local time zone for accurate timestamping of documents and events within Paperless-ngx.

```ini
PAPERLESS_OCR_LANGUAGE="eng"
PAPERLESS_TIME_ZONE="Europe/London"

```

--------------------------------

### Update Python Requirements (Bare Metal)

Source: https://docs.paperless-ngx.com/administration

Installs Python dependencies listed in the requirements.txt file for a bare metal Paperless-ngx installation. It's recommended to activate your virtual environment before running this command. Dependencies might be removed in newer versions, so comparing versions can help maintain a clean environment.

```bash
pip install -r requirements.txt
```

--------------------------------

### Django Localization: Compilemessages

Source: https://docs.paperless-ngx.com/development

Command to compile message files into a format that Django can use for localization. These compiled files are not committed to git and are handled by the build pipeline.

```python
python3 manage.py compilemessages
```

--------------------------------

### Django Localization: Makemessages

Source: https://docs.paperless-ngx.com/development

Command to extract translatable strings from the Django application into message files. This is crucial after any changes to translatable strings.

```python
python3 manage.py makemessages -l en_US
```

--------------------------------

### Creating PaperlessTask Failed due to DB Lock (Log)

Source: https://docs.paperless-ngx.com/troubleshooting

This log message indicates a database lock issue, likely occurring with an SQLite-based installation with multiple workers. This is due to SQLite's concurrency limitations. Consider switching to PostgreSQL, adjusting PAPERLESS_DB_TIMEOUT, or enabling Write-Ahead Logging for SQLite.

```log
[ERROR] [paperless.management.consumer] Creating PaperlessTask failed: db locked

```

--------------------------------

### Frontend Localization - Extract and Configure Strings

Source: https://docs.paperless-ngx.com/development

Commands and configuration snippets for frontend localization in AngularJS. This includes extracting translation strings and configuring supported locales in `angular.json` and `settings.service.ts`.

```bash
ng extract-i18n
```

```json
    "i18n": {
        "sourceLocale": "en-US",
        "locales": {
            "de": "src/locale/messages.de.xlf",
            "nl-NL": "src/locale/messages.nl_NL.xlf",
            "fr": "src/locale/messages.fr.xlf",
            "en-GB": "src/locale/messages.en_GB.xlf",
            "pt-BR": "src/locale/messages.pt_BR.xlf",
            "language-code": "language-file"
        }
    }
```

```typescript
`dateInputFormat` is a special string that defines the behavior of
the date input fields and absolutely needs to contain "dd", "mm"
and "yyyy".

```

```typescript
import localeDe from '@angular/common/locales/de'
registerLocaleData(localeDe)
```

--------------------------------

### Execute Management Commands (Bare Metal)

Source: https://docs.paperless-ngx.com/administration

Invokes management commands for a bare metal Paperless-ngx installation. Navigate to the '/path/to/paperless/src' directory first. Use '<command>' and '<arguments>' to specify the desired management task and its parameters. All commands support a '--help' argument for usage information.

```bash
cd /path/to/paperless/src
python3 manage.py <command> <arguments> # 
```

--------------------------------

### Paperless-ngx Configuration Example (Security and URL)

Source: https://docs.paperless-ngx.com/setup

Sets the secret key for authentication and the public URL if Paperless-ngx is accessed behind a reverse proxy. A strong, random secret key is crucial for security.

```ini
PAPERLESS_SECRET_KEY="your_strong_random_secret_key"
PAPERLESS_URL="https://your.domain.com"

```

--------------------------------

### Format and Test Frontend Code with Prettier, Jest, and Playwright

Source: https://docs.paperless-ngx.com/development

Commands for code formatting using Prettier and running tests using Jest (unit tests) and Playwright (e2e tests). Prettier is integrated with Git pre-commit hooks. Playwright also offers a UI mode.

```bash
$ git ls-files -- '*.ts' | xargs pre-commit run prettier --files
```

```bash
$ ng test
```

```bash
$ npx playwright test
```

```bash
$ npx playwright test --ui
```

--------------------------------

### Search Autocomplete Result Structure

Source: https://docs.paperless-ngx.com/api

An example JSON response from the `/api/search/autocomplete/` endpoint, returning an ordered list of suggested search terms.

```json
["term1", "term3", "term6", "term4"]
```

--------------------------------

### Add New Language to Django Settings

Source: https://docs.paperless-ngx.com/development

Configuration snippet for the `src/paperless/settings.py` file to add support for new languages in the Paperless-ngx application. This involves updating the LANGUAGES tuple.

```python
LANGUAGES = [
    ("en-us", _("English (US)")),
    ("en-gb", _("English (GB)")),
    ("de", _("German")),
    ("nl-nl", _("Dutch")),
    ("fr", _("French")),
    ("pt-br", _("Portuguese (Brazil)")),
    # Add language here.
]
```

--------------------------------

### Enable Flower Monitoring

Source: https://docs.paperless-ngx.com/configuration

This configuration enables the Celery monitoring tool, Flower, within the Paperless-ngx container. Defining the PAPERLESS_ENABLE_FLOWER environment variable is sufficient to start Flower.

```bash
PAPERLESS_ENABLE_FLOWER=<defined>
```

--------------------------------

### Migrate Database (Bare Metal)

Source: https://docs.paperless-ngx.com/administration

Applies database migrations for Paperless-ngx on a bare metal installation. Navigate to the 'src' directory before executing. A 'sudo' command might be necessary depending on file ownership. Not all versions require database migrations.

```bash
cd src
python3 manage.py migrate # (1)
```

--------------------------------

### Update Paperless Git Repository

Source: https://docs.paperless-ngx.com/setup

For users who installed Paperless using the bare-metal route, this command updates the Git remote URL to point to the Paperless-ngx repository, allowing them to pull the latest version.

```bash
git remote set-url origin https://github.com/paperless-ngx/paperless-ngx
```

--------------------------------

### Configure Docker Compose for Latest Paperless-ngx Version

Source: https://docs.paperless-ngx.com/administration

Example of how to modify the docker-compose.yml file to use the 'latest' tag for the paperless-ngx image, ensuring automatic updates to the newest stable release.

```yaml
image: ghcr.io/paperless-ngx/paperless-ngx:latest
```

--------------------------------

### Stop Paperless-ngx with Docker Compose

Source: https://docs.paperless-ngx.com/administration

This command stops the paperless-ngx services managed by Docker Compose. It is a prerequisite before performing updates or backups on Docker installations.

```bash
cd /path/to/paperless
docker compose down
```

--------------------------------

### Configure Docker Compose to Pin Paperless-ngx Release Series

Source: https://docs.paperless-ngx.com/administration

Example of modifying the docker-compose.yml to pin the paperless-ngx image to a specific release series (e.g., '1.7'). This is useful for controlled upgrades and integrations with tools like Watchtower.

```yaml
image: ghcr.io/paperless-ngx/paperless-ngx:1.7
```

--------------------------------

### Paperless-ngx Advanced Search Syntax Examples

Source: https://docs.paperless-ngx.com/usage

Demonstrates the advanced search syntax available in Paperless-ngx for refining document searches. This includes combining logical expressions, matching specific tags/correspondents/types, filtering by dates, and using inexact word matching. Note that inexact word matching can be resource-intensive.

```plaintext
shopname AND (product1 OR product2)

type:invoice tag:unpaid
correspondent:university certificate

created:[2005 to 2009]
added:yesterday
modified:today

produ*name
```

--------------------------------

### Shell Script Output Piping Example

Source: https://docs.paperless-ngx.com/advanced_usage

Illustrates how to pipe the output of a shell script to a log file using `tee --append`. This is useful for capturing script execution details, such as document IDs, for debugging purposes.

```bash
echo "${DOCUMENT_ID}" | tee --append /usr/src/paperless/scripts/post-consumption-example.log
```

--------------------------------

### GPG Email Decryption Test Commands

Source: https://docs.paperless-ngx.com/advanced_usage

These are example commands for testing GPG encryption and decryption, which are prerequisites for configuring Paperless-ngx to decrypt encrypted emails. The commands demonstrate encrypting a file for a recipient and then decrypting an armored file.

```bash
gpg --encrypt --armor -r person@email.com name_of_file
gpg --decrypt name_of_file.asc
```

--------------------------------

### Configure ASGI Server for Paperless-ngx Notifications

Source: https://docs.paperless-ngx.com/changelog

This configuration snippet is for bare metal installations of paperless-ngx to enable status notifications and live updates. It requires adapting the systemd service file to use an ASGI-enabled web server like gunicorn with uvicorn. Failure to configure this will result in notifications not working, although paperless will continue to function with WSGI.

```bash
ExecStart=/opt/paperless/.local/bin/gunicorn -c /opt/paperless/gunicorn.conf.py paperless.asgi:application
```

--------------------------------

### Pre-consumption Script Example: OCR PDF Document

Source: https://docs.paperless-ngx.com/advanced_usage

This bash script demonstrates how to perform OCR on a PDF document before it is fully consumed by Paperless-ngx. It utilizes the `DOCUMENT_WORKING_PATH` environment variable to access the document and overwrites it with an OCR'd version. This script is intended to be placed in `/usr/local/bin/ocr-pdf` and configured in `paperless.conf`.

```bash
#!/usr/bin/env bash
pdf2pdfocr.py -i ${DOCUMENT_WORKING_PATH}

```

--------------------------------

### Paperless-ngx Bulk Object Edit: Set Permissions for Correspondents

Source: https://docs.paperless-ngx.com/api

Example payload for setting permissions on multiple correspondents. Specifies the object type, operation, and the permissions object.

```json
{
  "objects": [50, 51],
  "object_type": "correspondents",
  "operation": "set_permissions",
  "permissions": {
    "view": { "users": [101], "groups": [201] },
    "change": { "users": [102] }
  },
  "merge": true
}
```

--------------------------------

### Document Search Result Structure

Source: https://docs.paperless-ngx.com/api

An example JSON response structure for a document search query, including pagination details and a `__search_hit__` attribute with relevance information.

```json
{
    "count": 31,
    "next": "http://localhost:8000/api/documents/?page=2&query=test",
    "previous": null,
    "results": [
        {
            "id": 123,
            "title": "title",
            "content": "content",
            "__search_hit__": {
                "score": 0.343,
                "highlights": "text <span class=\"match\">Test</span> text",
                "rank": 23
            }
        }
    ]
}
```

--------------------------------

### Update Paperless-ng Docker Image

Source: https://docs.paperless-ngx.com/setup

This snippet shows how to update the Docker image for Paperless-ng to Paperless-ngx in a Docker Compose setup. It involves changing the image tag in the `docker-compose.yml` file.

```yaml
image: jonaswinkler/paperless-ng:latest
```

```yaml
image: ghcr.io/paperless-ngx/paperless-ngx:latest
```

--------------------------------

### Full Text Search API Endpoint

Source: https://docs.paperless-ngx.com/api

Example of querying the `/api/documents/` endpoint for full text search results using the `query` parameter. The URL encodes the search term.

```http
/api/documents/?query=your%20search%20query
```

--------------------------------

### Paperless-ngx Document Bulk Edit: Add Tag

Source: https://docs.paperless-ngx.com/api

Example of a bulk edit operation to add a tag to multiple documents. Requires a tag ID as a parameter.

```json
{
  "documents": [4, 5, 6],
  "method": "add_tag",
  "parameters": { "tag": 25 }
}
```

--------------------------------

### Import Documents with Paperless-ngx CLI

Source: https://docs.paperless-ngx.com/administration

The document_importer script imports exported documents into Paperless-ngx. It accepts a source directory or a zip file and supports options to hide the progress bar, import data only, or use a passphrase for encrypted exports. It is recommended to run this on a clean installation.

```bash
document_importer source

```

--------------------------------

### Convert MariaDB UUID Command (Management Command)

Source: https://docs.paperless-ngx.com/troubleshooting

This management command is used to resolve 'Data too long for column 'transaction_id'' errors in MariaDB/MySQL installations that have upgraded from Paperless-ngx versions prior to v2.13.0 (Django 4). It re-creates the 'documents_document.transaction_id' column for compatibility with Django 5.

```bash
$ python3 manage.py convert_mariadb_uuid

```

--------------------------------

### Python Custom Document Parser Implementation for Paperless-ngx

Source: https://docs.paperless-ngx.com/development

This Python code defines a custom document parser for Paperless-ngx. It extends the base `DocumentParser` class and implements methods to extract content, generate a thumbnail, and optionally retrieve a creation date. The `parse` method populates attributes like `self.text`, `self.archive_path`, and `self.date`. The `get_thumbnail` method returns the path to a generated thumbnail. It utilizes `self.tempdir` for temporary files.

```python
class MyCustomParser(DocumentParser):

    def parse(self, document_path, mime_type):
        # This method does not return anything. Rather, you should assign
        # whatever you got from the document to the following fields:

        # The content of the document.
        self.text = "content"

        # Optional: path to a PDF document that you created from the original.
        self.archive_path = os.path.join(self.tempdir, "archived.pdf")

        # Optional: "created" date of the document.
        self.date = get_created_from_metadata(document_path)

    def get_thumbnail(self, document_path, mime_type):
        # This should return the path to a thumbnail you created for this
        # document.
        return os.path.join(self.tempdir, "thumb.webp")

```

--------------------------------

### Paperless-ngx Document Bulk Edit: Edit PDF Operations

Source: https://docs.paperless-ngx.com/api

Example payload for editing PDF documents in bulk. Demonstrates rotating pages and specifying output document indices.

```json
{
  "documents": [12],
  "method": "edit_pdf",
  "parameters": {
    "doc_ids": [12],
    "operations": [
      { "page": 1, "rotate": 90 },
      { "page": 2, "doc": 1 } // Split page 2 into a new document index 1
    ],
    "delete_original": true
  }
}
```

--------------------------------

### Configuring Gotenberg API Timeout (Docker Compose)

Source: https://docs.paperless-ngx.com/troubleshooting

This configuration snippet for `docker-compose.yml` increases the API timeout for Gotenberg, which is used for converting Office documents to PDF. It increases the timeout to 60 seconds to resolve 504 Gateway Timeout errors during conversion.

```yaml
command:
    - 'gotenberg'
    - '--chromium-disable-javascript=true'
    - '--chromium-allow-list=file:///tmp/.*'
    - '--api-timeout=60s'

```

--------------------------------

### Python Paperless-ngx Parser Declaration Handler

Source: https://docs.paperless-ngx.com/development

This Python function serves as a handler for the `document_consumer_declaration` signal in Paperless-ngx. It returns a dictionary containing information about a custom parser, including a reference to the parser class (`MyCustomParser`), its processing weight, and a mapping of supported MIME types to their default file extensions. This allows Paperless-ngx to recognize and utilize the custom parser.

```python
def myparser_consumer_declaration(sender, **kwargs):
    return {
        "parser": MyCustomParser,
        "weight": 0,
        "mime_types": {
            "application/pdf": ".pdf",
            "image/jpeg": ".jpg",
        }
    }

```

--------------------------------

### Configure Docker Compose Port Mapping

Source: https://docs.paperless-ngx.com/setup

This example demonstrates how to change the default port mapping for the Paperless-ngx webserver in a `docker-compose.yml` file. It shows how to map a host port (e.g., 8010) to the container's webserver port (8000).

```yaml
ports:
    - 8010:8000

```

--------------------------------

### Paperless-ngx Document Bulk Edit: Merge Documents

Source: https://docs.paperless-ngx.com/api

Example payload for merging multiple documents into a single document. Allows specifying metadata from a source document and deleting originals.

```json
{
  "documents": [13, 14, 15],
  "method": "merge",
  "parameters": {
    "metadata_document_id": 13,
    "delete_originals": true
  }
}
```

--------------------------------

### Configure Additional OCR Languages

Source: https://docs.paperless-ngx.com/configuration

Example of setting additional OCR languages for Paperless-ngx using the PAPERLESS_OCR_LANGUAGES environment variable. It requires a space-separated list of language codes (e.g., 'tur ces chi-tra'). Ensure the correct language codes for Tesseract OCR are used, which may differ from package names. For these languages to be active, PAPERLESS_OCR_LANGUAGE must also be set.

```bash
PAPERLESS_OCR_LANGUAGES=tur ces chi-tra
PAPERLESS_OCR_LANGUAGE=tur
```

--------------------------------

### Get Host User ID

Source: https://docs.paperless-ngx.com/configuration

Command to retrieve the user ID of the current user on the host system. This is used to set the USERMAP_UID environment variable for Paperless-ngx to ensure correct file ownership within the container.

```bash
id -u
```

--------------------------------

### Force OCR Processing on Rendering Errors (Configuration)

Source: https://docs.paperless-ngx.com/troubleshooting

To address Ghostscript PDF/A rendering failures where OCRmyPDF intentionally stops processing, set the PAPERLESS_OCR_USER_ARGS environment variable. This allows 'forcing' processing of documents with soft rendering errors.

```environment
PAPERLESS_OCR_USER_ARGS='{"continue_on_soft_render_error": true}'

```

--------------------------------

### Fix Docker Image Build (paperless-ngx 1.6.0)

Source: https://docs.paperless-ngx.com/changelog

A workaround for a malformed `package-lock.json` in version 1.6.0 that affects users building the Docker image from source. This command updates npm and installs dependencies using legacy peer dependencies to resolve build issues.

```Dockerfile
RUN npm update npm -g && npm install --legacy-peer-deps
```

--------------------------------

### Create System User for Paperless-ngx

Source: https://docs.paperless-ngx.com/setup

Creates a dedicated system user named 'paperless' with a home directory at '/opt/paperless'. This user will run the Paperless-ngx service, ensuring proper isolation and permissions.

```bash
adduser paperless --system --home /opt/paperless --group
```

--------------------------------

### Filter for Non-existent Custom Field

Source: https://docs.paperless-ngx.com/api

Example of filtering documents that do not have a custom field named 'foo'.

```http
?custom_field_query=["foo", "exists", false]
```

--------------------------------

### OSError: No such device (Python/mmap)

Source: https://docs.paperless-ngx.com/troubleshooting

Resolves the 'OSError: [Errno 19] No such device' when Paperless-ngx encounters issues creating or opening memory-mapped files for its search index. This error often arises when the data directory is located on file systems, particularly network shares, that do not support memory-mapped files (mmap). Ensure your data directory is on a supported local file system.

```python
import mmap
import os

def check_mmap_support(directory):
    try:
        # Attempt to create a dummy file and memory-map it
        dummy_file_path = os.path.join(directory, "mmap_test_file.tmp")
        with open(dummy_file_path, "wb") as f:
            f.seek(1024 * 1024 - 1) # Create a 1MB file
            f.write(b"\0")
        
        with open(dummy_file_path, "r+b") as f:
            with mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_WRITE) as mm:
                mm[0] = b'a'
        
        os.remove(dummy_file_path)
        return True
    except (OSError, TypeError, NotImplementedError):
        # OSError: [Errno 19] No such device is a common indicator
        # TypeError or NotImplementedError can also occur on unsupported systems
        return False

# Example usage:
data_directory = "/path/to/paperless/data"
if not check_mmap_support(data_directory):
    print(f"Warning: Memory-mapped files (mmap) may not be supported on {data_directory}. Search index may fail.")
else:
    print(f"Memory-mapped files appear to be supported on {data_directory}.")

```

--------------------------------

### Permission Denied Error in Consumption Directory (Shell)

Source: https://docs.paperless-ngx.com/troubleshooting

Addresses 'Permission denied' errors when Paperless-ngx attempts to delete files in the consumption directory. This typically occurs when the user running Paperless lacks the necessary permissions. Ensure USERMAP_UID and USERMAP_GID are correctly set if they differ from 1000, and verify read/write access to the consumption directory on the host system.

```shell
# Example: Check and set permissions on the consumption directory (replace with your actual directory)
sudo chown -R <your_user>:<your_group> /path/to/paperless/consume
sudo chmod -R u+rwX /path/to/paperless/consume

```

--------------------------------

### Download Paperless-ngx Release Archive

Source: https://docs.paperless-ngx.com/setup

Downloads a specific release version of the Paperless-ngx source code archive using curl. Replace `v1.10.2` with the desired version.

```bash
curl -O -L https://github.com/paperless-ngx/paperless-ngx/releases/download/v1.10.2/paperless-ngx-v1.10.2.tar.xz
```

--------------------------------

### Create Paperless-ngx Database Schema

Source: https://docs.paperless-ngx.com/setup

This command creates the database schema for Paperless-ngx. It is executed as the paperless user and is a crucial step before the application can be used.

```bash
# This creates the database schema.
sudo -Hu paperless python3 manage.py migrate
```

--------------------------------

### Paperless-ngx Document Bulk Edit: Delete Documents

Source: https://docs.paperless-ngx.com/api

Example of a bulk edit operation to delete multiple documents. This operation does not require any additional parameters.

```json
{
  "documents": [9, 10, 11],
  "method": "delete"
}
```

--------------------------------

### Filter by Custom Text Exact Match

Source: https://docs.paperless-ngx.com/api

Example of filtering documents where a custom text field 'customer' exactly matches 'bob', with case sensitivity.

```http
?custom_field_query=["customer", "exact", "bob"]
```

--------------------------------

### Execute Management Commands (Docker Compose)

Source: https://docs.paperless-ngx.com/administration

Runs management commands for a Paperless-ngx instance managed with Docker Compose. Navigate to the Paperless directory before executing. Replace '<command>' and '<arguments>' with the desired management task and its parameters.

```bash
cd /path/to/paperless
docker compose exec webserver <command> <arguments>
```

--------------------------------

### Verify GPG Agent and Keyring Permissions

Source: https://docs.paperless-ngx.com/advanced_usage

This command lists the contents of the GPG directory within the paperless container, allowing you to verify the permissions and existence of the GPG agent socket and public keyring. Ensure the paperless user has the necessary read/write access.

```bash
paperless@9da1865df327:~/.gnupg$ ls -al
drwx------ 1 paperless paperless   4096 Aug 18 17:52 .
drwxr-xr-x 1 paperless paperless   4096 Aug 18 17:52 ..
srw------- 1 paperless paperless      0 Aug 18 17:22 S.gpg-agent
-rw------- 1 paperless paperless 147940 Jul 24 10:23 pubring.gpg
```

--------------------------------

### Paperless-ngx Document Bulk Edit: Set Correspondent

Source: https://docs.paperless-ngx.com/api

Example of a bulk edit operation to set a correspondent for multiple documents. Requires a correspondent ID as a parameter.

```json
{
  "documents": [1, 2, 3],
  "method": "set_correspondent",
  "parameters": { "correspondent": 10 }
}
```

--------------------------------

### Reindex Documents for Paperless-ngx

Source: https://docs.paperless-ngx.com/setup

This command initiates a one-time operation to create the search index for Paperless-ngx. It is crucial for the new search feature to find existing documents and also migrates the database.

```bash
docker compose run --rm webserver document_index reindex
```

--------------------------------

### Specify External Binary Path (String)

Source: https://docs.paperless-ngx.com/configuration

Sets the literal path for external software packages that Paperless-ngx requires, such as 'convert' or 'gs'. This is necessary if these programs are not in the system's $PATH.

```plaintext
<path>
```

```plaintext
convert
```

```plaintext
gs
```

--------------------------------

### Clone Paperless-ngx Repository

Source: https://docs.paperless-ngx.com/setup

This command clones the Paperless-ngx Git repository from GitHub. It is used to obtain the source code for building the Docker image locally. The main branch typically reflects the latest stable version.

```bash
git clone https://github.com/paperless-ngx/paperless-ngx

```

--------------------------------

### Build and Update Paperless-ngx Docker Image

Source: https://docs.paperless-ngx.com/administration

Commands to update the source code, rebuild the paperless-ngx Docker image, and restart the services. This is used when you have built the image yourself.

```bash
git pull
docker compose build
docker compose up
```

--------------------------------

### Build Docker Image

Source: https://docs.paperless-ngx.com/setup

This command builds the Paperless-ngx Docker image from the source code in the current directory. It is used as an alternative to `docker compose pull` when you have chosen to build the image yourself.

```bash
docker compose build

```

--------------------------------

### Paperless-ngx Document Bulk Edit: Delete Document Pages

Source: https://docs.paperless-ngx.com/api

Example payload for deleting specific pages from a single document. Requires a list of page numbers to remove.

```json
{
  "documents": [18],
  "method": "delete_pages",
  "parameters": {
    "pages": [2, 4, 5]
  }
}
```

--------------------------------

### Execute Management Commands (Docker)

Source: https://docs.paperless-ngx.com/administration

Executes management commands for a running Paperless-ngx Docker container. Replace '<container-name>', '<command>', and '<arguments>' with the specific container name and the management task details.

```bash
docker exec -it <container-name> <command> <arguments>
```

--------------------------------

### Paperless-ngx Document Bulk Edit: Rotate Document

Source: https://docs.paperless-ngx.com/api

Example payload for rotating a single document by a specified number of degrees. Accepts 90, 180, or 270 degrees.

```json
{
  "documents": [17],
  "method": "rotate",
  "parameters": {
    "degrees": 180
  }
}
```

--------------------------------

### Paperless-ngx Bulk Object Edit: Delete Tags

Source: https://docs.paperless-ngx.com/api

Example payload for bulk deleting multiple tags. Requires a list of tag IDs and specifies the object type as 'tags'.

```json
{
  "objects": [40, 41, 42],
  "object_type": "tags",
  "operation": "delete"
}
```

--------------------------------

### Allow Social Account Signups

Source: https://docs.paperless-ngx.com/configuration

Enables or disables user account creation via any configured third-party authentication systems. Defaults to True.

```shell
PAPERLESS_SOCIALACCOUNT_ALLOW_SIGNUPS=True
```

```shell
PAPERLESS_SOCIALACCOUNT_ALLOW_SIGNUPS=False
```

--------------------------------

### Docker Compose Volume Mounts for GPG

Source: https://docs.paperless-ngx.com/advanced_usage

These volume mounts in `docker-compose.yml` are essential for allowing Paperless-ngx, when run in Docker, to access your host's GPG agent socket and public keyring. Replace `<path to gpg-agent socket>` with the actual path obtained from `gpgconf --list-dir agent-socket`.

```yaml
webserver:
    volumes:
        - /home/user/.gnupg/pubring.gpg:/usr/src/paperless/.gnupg/pubring.gpg
        - <path to gpg-agent socket>:/usr/src/paperless/.gnupg/S.gpg-agent
```

--------------------------------

### Paperless-ngx Document Bulk Edit: Split Document

Source: https://docs.paperless-ngx.com/api

Example payload for splitting a single document into multiple documents based on specified page ranges. Supports deleting the original document.

```json
{
  "documents": [16],
  "method": "split",
  "parameters": {
    "pages": "[1,3-5,7]",
    "delete_originals": true
  }
}
```

--------------------------------

### Enable/Disable User Signups

Source: https://docs.paperless-ngx.com/configuration

Controls whether new users can create accounts directly within Paperless-ngx. Defaults to False, requiring manual user creation or social account signup.

```shell
PAPERLESS_ACCOUNT_ALLOW_SIGNUPS=True
```

```shell
PAPERLESS_ACCOUNT_ALLOW_SIGNUPS=False
```

--------------------------------

### Check Directory Permissions for Paperless-ngx

Source: https://docs.paperless-ngx.com/setup

This command checks the permissions of the specified media directory. It is crucial to ensure the paperless user has write permissions to the consumption and media directories for proper operation.

```bash
ls -l -d /opt/paperless/media
```

--------------------------------

### Paperless-ngx Document Bulk Edit: Modify Custom Fields

Source: https://docs.paperless-ngx.com/api

Example payload for adding or removing custom fields from documents. Supports adding fields with values or empty values, and removing existing fields.

```json
{
  "documents": [19, 20],
  "method": "modify_custom_fields",
  "parameters": {
    "add_custom_fields": {
      "cf_invoice_number": "INV-12345",
      "cf_project_code": "PROJ-ABC"
    },
    "remove_custom_fields": ["old_custom_field_id"]
  }
}
```

--------------------------------

### Document Exporter Command-Line Arguments

Source: https://docs.paperless-ngx.com/administration

Lists the available command-line arguments for the document_exporter utility. These options control aspects like checksum comparison, deletion of old files, filename formatting, thumbnail inclusion, and zip compression.

```text
document_exporter target [-c] [-d] [-f] [-na] [-nt] [-p] [-sm] [-z] [--data-only] [--no-progress-bar] [--passphrase]

optional arguments:
-c,  --compare-checksums
-cj, --compare-json
-d,  --delete
-f,  --use-filename-format
-na, --no-archive
-nt, --no-thumbnail
-p,  --use-folder-prefix
-sm, --split-manifest
-z,  --zip
-zn, --zip-name
--data-only
--no-progress-bar
--passphrase
```

--------------------------------

### Database Unique Constraint Violation (Log)

Source: https://docs.paperless-ngx.com/troubleshooting

This database log indicates a duplicate key violation for the 'documents_tag_name_uniq' constraint, often seen during heavy consumption with polling. Paperless handles this correctly, and the file will still be consumed.

```log
ERROR:  duplicate key value violates unique constraint "documents_tag_name_uniq"
DETAIL:  Key (name)=(NameF) already exists.
STATEMENT:  INSERT INTO "documents_tag" ("owner_id", "name", "match", "matching_algorithm", "is_insensitive", "color", "is_inbox_tag") VALUES (NULL, 'NameF', '', 1, true, '#a6cee3', false) RETURNING "documents_tag"."id"

```

--------------------------------

### Paperless-ngx Document Bulk Edit: Modify Tags (Add and Remove)

Source: https://docs.paperless-ngx.com/api

Example of a bulk edit operation to modify tags on documents, including adding and removing tags simultaneously. Requires lists of tag IDs.

```json
{
  "documents": [7, 8],
  "method": "modify_tags",
  "parameters": {
    "add_tags": [30, 31],
    "remove_tags": [25]
  }
}
```

--------------------------------

### Get Host Group ID

Source: https://docs.paperless-ngx.com/configuration

Command to retrieve the group ID of the current user on the host system. This is used to set the USERMAP_GID environment variable for Paperless-ngx to ensure correct group ownership of files within the container.

```bash
id -g
```

--------------------------------

### Granian Port Number Error (Configuration)

Source: https://docs.paperless-ngx.com/troubleshooting

This error occurs when running Paperless-ngx in Kubernetes, where an environment variable like ${serviceName}_PORT conflicts with PAPERLESS_PORT. Set PAPERLESS_PORT explicitly to your desired port or the default of 8000 to resolve this.

--------------------------------

### Verify Docker Volume Names

Source: https://docs.paperless-ngx.com/setup

This command lists all Docker volumes and filters them to show volumes ending with '_data'. This is useful for verifying volume names when migrating Paperless-ngx and ensuring it uses the old Paperless volumes.

```bash
docker volume ls | grep _data
```

--------------------------------

### Construct Path by MIME Type

Source: https://docs.paperless-ngx.com/advanced_usage

Constructs file paths based on the document's MIME type. It categorizes documents into 'pdfs', 'pngs', or 'others' before appending the document title. This allows for organizing files by their format.

```jinja
{% if document.mime_type == "application/pdf" %}
  pdfs
{% elif document.mime_type == "image/png" %}
  pngs
{% else %}
  others
{% endif %}
/{{ title }}
```

--------------------------------

### Update Paperless-ngx Docker Images

Source: https://docs.paperless-ngx.com/administration

Commands to pull the latest stable release of paperless-ngx and restart the services. This is the standard update procedure when using Docker Hub images.

```bash
docker compose pull
docker compose up
```

--------------------------------

### Authentication

Source: https://docs.paperless-ngx.com/api

Details on how to authenticate with the Paperless-ngx REST API using Basic, Session, Token, or Remote User authentication.

```APIDOC
## Authentication

The REST API supports four authentication methods:

### 1. Basic Authentication
Use Basic Authentication by providing a `Authorization` header.

**Header Format:**
```
Authorization: Basic <credentials>
```
`<credentials>` is a base64-encoded string of `<username>:<password>`.

### 2. Session Authentication
If you are logged into the Paperless UI in your browser, you are automatically authenticated for the API.

### 3. Token Authentication
Generate an API token from the "My Profile" page in the web UI or via the `/api/token/` endpoint.

**Acquire Token Endpoint:**

#### POST /api/token/

**Description:** Obtain an authentication token by providing username and password.

**Request Body:**
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

**Response:**
- **token** (string) - The authentication token.

**Header Format for Authenticated Requests:**
```
Authorization: Token <token>
```

### 4. Remote User Authentication
If enabled via configuration, you can authenticate using Remote User authentication.
```

--------------------------------

### Configure Docker Compose Volume Mounts

Source: https://docs.paperless-ngx.com/setup

This snippet shows how to configure volume mounts in a `docker-compose.yml` file. It illustrates changing the host path for the consumption directory to be mounted into the container. Ensure the host path is a valid local directory.

```yaml
- ./consume:/usr/src/paperless/consume

```

```yaml
- /home/jonaswinkler/paperless-inbox:/usr/src/paperless/consume

```

--------------------------------

### Configure Barcode to Tag Mapping (JSON/Python Regex)

Source: https://docs.paperless-ngx.com/configuration

Defines a dictionary to map barcode patterns to tag values using regular expressions. This allows for flexible reformatting and creation of tags based on barcode content. Supports standard Python regex syntax. Defaults to stripping a 'TAG:' prefix.

```json
{
  "<regex>": "<substitute>" [,...]
}
```

```json
{
  "TAG:(.*)": "\g<1>"
}
```

```json
{
  "ASN12.*": "JOHN", 
  "ASN13.*": "SMITH"
}
```

```json
{
  "T-J": "JOHN", 
  "T-S": "SMITH", 
  "T-D": "DOE"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.