Paperless-ngx

https://docs.paperless-ngx.com/
Admin
Paperless-ngx is a community-supported open-source document management system that transforms...
Tokens:110,202
Snippets:868
Trust Score:7.3
Update:5 days ago
Show doc for...
Tokens:
Raw
### Test webserver

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

Manually start the webserver to test the installation.

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

```

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

### Run Paperless-ngx installation script

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

Use this command to download and run the official Paperless-ngx installation script. It requires Docker and Docker Compose to be installed. macOS users need GNU sed and wget. The script is interactive and will create configuration files, pull the image, start containers, and create a superuser account.

```bash
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

```

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

### Build and start Docker image from source

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

If you built the image yourself, pull the latest source, rebuild, and start.

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

```

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

### Install Tesseract language pack (Spanish example)

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

Run this command on Ubuntu/Debian to install the Tesseract language files for Spanish, which resolves OCR accuracy issues and the 'OCR for XX failed' warning when FORGIVING_OCR is enabled.

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

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

### Start Paperless-ngx with docker compose up -d

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

Start Paperless-ngx in the background and enable auto-start on system boot.

```bash
docker compose up -d

```

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

### Install pre-commit hooks

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

Installs the pre-commit hooks for the repository.

```bash
uv run prek install

```

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

### Start the consumer with document_consumer

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

Management command to start the Paperless-ngx consumer process. Run from the src directory.

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

```

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

### Start the webserver with granian

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

Command to start the Paperless-ngx webserver directly using granian with the ASGI application. Run from the src directory.

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

```

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

### Shell Script: Install Third-Party Parser Plugin

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

A custom container initialization script to install a third-party parser plugin before the webserver starts. Mount this script into /custom-cont-init.d. The script is run by the root user.

```bash
#!/bin/bash

```

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

### Install front end dependencies

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

Installs all necessary modules for the front end using pnpm.

```bash
pnpm install

```

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

### Install Python dependencies

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

Install all Python dependencies from requirements.txt as the paperless user.

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

```

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

### Install parser plugin as paperless user (bare metal)

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

Install the package into the same Python environment that runs Paperless-ngx. For standard bare-metal installs, use the paperless user's environment.

```bash
sudo -Hu paperless pip3 install my-paperless-parser-package
```

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

### Install Python dependencies with uv

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

Installs the development dependencies for the project using uv.

```bash
uv sync --group dev

```

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

### Install parser plugin with uv or virtual environment

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

If using uv or a virtual environment, activate it first and then run either command. Restart all Paperless-ngx services after installation so the new plugin is discovered.

```bash
uv pip install my-paperless-parser-package
# or
pip install my-paperless-parser-package
```

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

### Start all back-end development servers

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

Starts the Django development server, the document consumer, and the Celery worker in the background. The comment '# src/' indicates the command should be run from the src/ directory.

```bash
# src/

uv run manage.py runserver & \
  uv run manage.py document_consumer & \
  uv run celery --app paperless worker -l DEBUG

```

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

### Registering a plugin via pyproject.toml entry point

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

Register your plugin using a setuptools entry point in the [project.entry-points."paperless_ngx.date_parsers"] section. The entry point name is used for sorting; the first plugin alphabetically is selected.

```toml
[project.entry-points."paperless_ngx.date_parsers"]
my_parser = "my_package.parsers:MyDateParserPlugin"

```

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

### Create consume and media directories

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

Creates the required 'consume' and 'media' directories in the project root.

```bash
mkdir -p consume media

```

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

### Get GPG Agent Socket Path

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

Run this command to determine your local gpg-agent socket path, needed for the GPG decryptor setup.

```bash
gpgconf --list-dir agent-socket
```

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

### PAPERLESS_CONSUMER_IGNORE_PATTERNS example custom patterns

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

Example JSON array of regex patterns to ignore files in the consumption directory. Patterns are matched against filenames using Python's re.search(). Use ^ to anchor to start and $ to anchor to end. This setting is for additional patterns beyond built-in defaults.

```json
["^temp_", "\.bak$", "^~"]
```

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

### Mount plugin install script in docker-compose.yml

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

Mount the script directory into the container's /custom-cont-init.d directory. The script runs as root before the webserver starts, making the package available when Paperless-ngx discovers plugins at startup.

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

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

### Environment variable migration examples

Source: https://docs.paperless-ngx.com/migration-v3

Shows how to update environment variables from v2 to v3 equivalents for OCR and archive file generation settings. Includes comments for each case.

```bash
# v2: skip OCR when text present, always archive
PAPERLESS_OCR_MODE=skip
# v3: equivalent
PAPERLESS_OCR_MODE=auto
PAPERLESS_ARCHIVE_FILE_GENERATION=always

# v2: skip OCR when text present, skip archive too
PAPERLESS_OCR_MODE=skip_noarchive
# v3: equivalent
PAPERLESS_OCR_MODE=auto
PAPERLESS_ARCHIVE_FILE_GENERATION=never

# v2: always skip archive
PAPERLESS_OCR_SKIP_ARCHIVE_FILE=always
# v3: equivalent
PAPERLESS_ARCHIVE_FILE_GENERATION=never

# v2: skip archive only for born-digital docs
PAPERLESS_OCR_SKIP_ARCHIVE_FILE=with_text
# v3: equivalent (auto is the new default)
PAPERLESS_ARCHIVE_FILE_GENERATION=auto

```

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

### Example Directory Structure with Custom Filename Format

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

Shows the resulting directory structure when using the PAPERLESS_FILENAME_FORMAT configuration above. Documents are organized by year and correspondent, with titles as filenames. Duplicate titles get a numeric suffix (e.g., Letter_01.pdf).

```text
2019/
  My bank/
    Statement January.pdf
    Statement February.pdf
2020/
  My bank/
    Statement January.pdf
    Letter.pdf
    Letter_01.pdf
  Shoe store/
    My new shoes.pdf
```

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

### Build documentation with Zensical

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

Builds the documentation locally using Zensical. Run this command from the project root.

```bash
$ uv run zensical build

```

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

### Serve documentation with Zensical

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

Serves the documentation locally at http://127.0.0.1:8000 with automatic refresh on changes.

```bash
$ uv run zensical serve

```

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

### GET /api/search/autocomplete/ - Get autocomplete suggestions

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

Get auto completions for a partial search term. Results are ordered by how many of the user's visible documents contain each matching word.

```APIDOC
## [GET] /api/search/autocomplete/

### Description
Get auto completions for a partial search term. Results are ordered by how many of the user's visible documents contain each matching word.

### Method
GET

### Endpoint
/api/search/autocomplete/

### Parameters
#### Query Parameters
- **term** (string) - Required - The incomplete term.
- **limit** (integer) - Optional - Amount of results. Defaults to 10.

### Response
#### Success Response (200)
- **array of strings** - List of autocomplete suggestions.

#### Response Example
["term1", "term3", "term6", "term4"]
```

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

### Build the front end once

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

Installs front-end dependencies and builds the Angular application for production. The comment '# src-ui/' indicates the command should be run from the src-ui/ directory.

```bash
# src-ui/

pnpm install
pnpm ng build --configuration production

```

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

### Startup log line verifying parser discovery

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

Check the application logs at startup for a line like this to verify discovery.

```text
Loaded third-party parser 'My Format Parser' v1.0.0 by Acme Corp (entrypoint: 'my_parser').
```

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

### Install Angular CLI globally

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

Installs the Angular CLI globally using pnpm. May require sudo privileges.

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

```

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

### Build front end for production

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

Builds the front end with production configuration, placing it for Django to serve as static content.

```bash
pnpm ng build --configuration production

```

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

### Start a Valkey broker container

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

Starts a Docker container running Valkey (a Redis-compatible broker) on port 6379, with restart policy 'unless-stopped'.

```bash
docker run -d -p 6379:6379 --restart unless-stopped docker.io/valkey/valkey:9-alpine

```

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

### Jinja2 template examples for date localization in workflow titles

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

Two examples showing how to use the localize_date filter with different locales. The first outputs 'January' for the created date in en_US, the second outputs 'Juni' for the added date in de_DE. Note the codespell:ignore comment in the second example.

```jinja
{{ created | localize_date('MMMM', 'en_US') }}
<!-- Output: "January" -->
```

```jinja
{{ added | localize_date('MMMM', 'de_DE') }}
<!-- Output: "Juni" --> # codespell:ignore
```
Tokens:
Raw