Configuration - Paperless-ngx
Author: the Paperless-ngx team
Description: Documentation for the Paperless-ngx document management system software.

Skip to content

# Configuration

Paperless provides a wide range of customizations. Depending on how you run paperless, these settings have to be defined in different places.

Certain configuration options may be set via the UI. This currently includes common OCR related settings and some frontend settings. If set, these will take preference over the settings via environment variables. If not set, the environment setting or applicable default will be utilized instead.

- If you run paperless on docker, `paperless.conf` is not used. Rather, configure paperless by copying necessary options to `docker-compose.env`.

- If you are running paperless on anything else, paperless will search for the configuration file in these locations and use the first one it finds:

- The environment variable `PAPERLESS_CONFIGURATION_PATH`
- `/path/to/paperless/paperless.conf`
- `/etc/paperless.conf`
- `/usr/local/etc/paperless.conf`

## Required services

### Message Broker

Paperless-ngx uses a Redis-compatible message broker. Any broker that speaks the Redis protocol works here, including Valkey (the default in the bundled Docker Compose files) and Redis itself.

#### `PAPERLESS_REDIS=<url>`

  This is required for processing scheduled tasks such as email fetching, index optimization and for training the automatic document matcher.

  - If your broker needs login credentials PAPERLESS_REDIS = `redis://<username>:<password>@<host>:<port>`
  - With the requirepass option PAPERLESS_REDIS = `redis://:<password>@<host>:<port>`
  - To include the database index PAPERLESS_REDIS = `redis://<username>:<password>@<host>:<port>/<DBIndex>`

  More information on securing your broker instance.

  Defaults to `redis://localhost:6379`.

#### `PAPERLESS_REDIS_PREFIX=<prefix>`

  Prefix to be used in the broker for keys and channels. Useful for sharing one broker among multiple Paperless instances.

  Defaults to no prefix.

### Database

By default, Paperless uses SQLite with a database stored at `data/db.sqlite3`. For multi-user or higher-throughput deployments, PostgreSQL (recommended) or MariaDB can be used instead by setting `PAPERLESS_DBENGINE` and the relevant connection variables.

#### `PAPERLESS_DBENGINE=<engine>`

  Specifies the database engine to use. Accepted values are `sqlite`, `postgresql`, and `mariadb`. PostgreSQL and MariaDB users must set this explicitly.

  PostgreSQL and MariaDB both require `PAPERLESS_DBHOST` to be set. SQLite does not use any other connection variables; the database file is always located at `<PAPERLESS_DATA_DIR>/db.sqlite3`.

  Defaults to `sqlite`.

  Warning

  Using MariaDB comes with some caveats. See MySQL Caveats.

#### `PAPERLESS_DBHOST=<hostname>`

  Hostname of the PostgreSQL or MariaDB database server. Required when `PAPERLESS_DBENGINE` is `postgresql` or `mariadb`.

#### `PAPERLESS_DBPORT=<port>`

  Port to use when connecting to PostgreSQL or MariaDB.

  Defaults to `5432` for PostgreSQL and `3306` for MariaDB.

#### `PAPERLESS_DBNAME=<name>`

  Name of the PostgreSQL or MariaDB database to connect to.

  Defaults to `paperless`.

#### `PAPERLESS_DBUSER=<user>`

  Username for authenticating with the PostgreSQL or MariaDB database.

  Defaults to `paperless`.

#### `PAPERLESS_DBPASS=<password>`

  Password for the PostgreSQL or MariaDB database user.

  Defaults to `paperless`.

#### `PAPERLESS_DB_OPTIONS=<options>`

  Advanced database connection options as a comma-delimited key-value string. Keys and values are separated by `=`. Dot-notation produces nested option dictionaries; for example, `pool.max_size=20` sets `OPTIONS["pool"]["max_size"] = 20`.

  Options specified here are merged over the engine defaults. Unrecognised keys are passed through to the underlying database driver without validation, so a typo will be silently ignored rather than producing an error.

  Refer to your database driver's documentation for the full set of accepted keys:

  - PostgreSQL: libpq connection parameters
  - MariaDB: MariaDB Connector/Python
  - SQLite: SQLite PRAGMA statements

  PostgreSQL connection pooling

  Pool size is controlled via `pool.min_size` and `pool.max_size`. When configuring pooling, ensure your PostgreSQL `max_connections` is large enough to handle all pool connections across all workers: `(web_workers + celery_workers) * pool.max_size + safety_margin`.

  SQLite defaults

  SQLite connections are pre-configured with WAL journal mode, optimised synchronous and cache settings, and a 5-second busy timeout. These defaults suit most deployments. To override `init_command`, use `;` between PRAGMAs within the value and `,` between options:

      PAPERLESS_DB_OPTIONS="init_command=PRAGMA journal_mode=DELETE;PRAGMA synchronous=FULL,transaction_mode=DEFERRED"

  MariaDB: READ COMMITTED isolation level

  MariaDB connections default to `READ COMMITTED` isolation level, which eliminates gap locking and reduces deadlock frequency. If binary logging is enabled on your MariaDB server, this requires `binlog_format=ROW` (the default for most managed MariaDB instances). Statement-based replication is not compatible with `READ COMMITTED`.

  Examples:

  PostgreSQL: require SSL, set a custom CA certificate, and limit the pool size

      PAPERLESS_DB_OPTIONS="sslmode=require,sslrootcert=/certs/ca.pem,pool.max_size=5"

  MariaDB: require SSL with a custom CA certificate

      PAPERLESS_DB_OPTIONS="ssl_mode=REQUIRED,ssl.ca=/certs/ca.pem"

  PostgreSQL or MariaDB: set a connection timeout

      PAPERLESS_DB_OPTIONS="connect_timeout=10"

#### `PAPERLESS_DBSSLMODE`

Removed in v3

Use `PAPERLESS_DB_OPTIONS` instead.

PostgreSQL

    PAPERLESS_DB_OPTIONS="sslmode=require"

MariaDB

    PAPERLESS_DB_OPTIONS="ssl_mode=REQUIRED"

#### `PAPERLESS_DBSSLROOTCERT`

Removed in v3

Use `PAPERLESS_DB_OPTIONS` instead.

PostgreSQL

    PAPERLESS_DB_OPTIONS="sslrootcert=/path/to/ca.pem"

MariaDB

    PAPERLESS_DB_OPTIONS="ssl.ca=/path/to/ca.pem"

#### `PAPERLESS_DBSSLCERT`

Removed in v3

Use `PAPERLESS_DB_OPTIONS` instead.

PostgreSQL

    PAPERLESS_DB_OPTIONS="sslcert=/path/to/client.crt"

MariaDB

    PAPERLESS_DB_OPTIONS="ssl.cert=/path/to/client.crt"

#### `PAPERLESS_DBSSLKEY`

Removed in v3

Use `PAPERLESS_DB_OPTIONS` instead.

PostgreSQL

    PAPERLESS_DB_OPTIONS="sslkey=/path/to/client.key"

MariaDB

    PAPERLESS_DB_OPTIONS="ssl.key=/path/to/client.key"

#### `PAPERLESS_DB_TIMEOUT`

Removed in v3

Use `PAPERLESS_DB_OPTIONS` instead.

SQLite

    PAPERLESS_DB_OPTIONS="timeout=30"

PostgreSQL or MariaDB

    PAPERLESS_DB_OPTIONS="connect_timeout=30"

#### `PAPERLESS_DB_POOLSIZE`

Removed in v3

Use `PAPERLESS_DB_OPTIONS` instead.

    PAPERLESS_DB_OPTIONS="pool.max_size=10"

#### `PAPERLESS_DB_READ_CACHE_ENABLED=<bool>`

  Caches the database read query results into the broker. This can significantly improve application response times by caching database queries, at the cost of slightly increased memory usage.

  Defaults to `false`.

  Danger

  Do not modify the database outside the application while it is running. This includes actions such as restoring a backup, upgrading the database, or performing manual inserts. All external modifications must be done only when the application is stopped. After making any such changes, you must invalidate the DB read cache using the `invalidate_cachalot` management command.

#### `PAPERLESS_READ_CACHE_TTL=<int>`

  Specifies how long (in seconds) read data should be cached.

  Allowed values are between `1` (one second) and `31536000` (one year). Defaults to `3600` (one hour).

  Warning

  A high TTL increases memory usage over time. Memory may be used until end of TTL, even if the cache is invalidated with the `invalidate_cachalot` command.

In case of an out-of-memory (OOM) situation, the broker may stop accepting new data — including cache entries, scheduled tasks, and documents to consume. If your system has limited RAM, consider configuring a dedicated broker instance for the read cache, with a memory limit and the eviction policy set to `allkeys-lru`. For more details, refer to the Redis eviction policy documentation, and see the `PAPERLESS_READ_CACHE_REDIS_URL` setting to specify a separate broker.

#### `PAPERLESS_READ_CACHE_REDIS_URL=<url>`

  Defines the broker instance used for the read cache.

  Defaults to `None`.

  Note

  If this value is not set, the same broker instance used for scheduled tasks will be used for caching as well.

## Optional Services

### Tika

Paperless can make use of Tika and Gotenberg for parsing and converting "Office" documents (such as ".doc", ".xlsx" and ".odt"). Tika and Gotenberg are also needed to allow parsing of E-Mails (.eml).

If you wish to use this, you must provide a Tika server and a Gotenberg server, configure their endpoints, and enable the feature.

#### `PAPERLESS_TIKA_ENABLED=<bool>`

  Enable (or disable) the Tika parser.

  Defaults to false.

#### `PAPERLESS_TIKA_ENDPOINT=<url>`

  Set the endpoint URL where Paperless can reach your Tika server.

  Defaults to "http://localhost:9998".

#### `PAPERLESS_TIKA_GOTENBERG_ENDPOINT=<url>`

  Set the endpoint URL where Paperless can reach your Gotenberg server.

  Defaults to "http://localhost:3000".

If you run paperless on docker, you can add those services to the Docker Compose file (see the provided `docker-compose.sqlite-tika.yml` file for reference).

Add all three configuration parameters to your configuration. If using Docker, this may be the `environment` key of the webserver or a `docker-compose.env` file. Bare metal installations may have a `.conf` file containing the configuration parameters. Be sure to use the correct format and watch out for indentation if editing the YAML file.

### Email Parsing

#### `PAPERLESS_EMAIL_PARSE_DEFAULT_LAYOUT=<int>`

  The default layout to use for emails that are consumed as documents. Must be one of the integer choices below. Note that mail rules can specify this setting, thus this fallback is used for the default selection and for .eml files consumed by other means.

  - `1` = Text, then HTML
  - `2` = HTML, then text
  - `3` = HTML only
  - `4` = Text only

## Paths and folders

#### `PAPERLESS_CONSUMPTION_DIR=<path>`

  This is where your documents should go to be consumed. Make sure that it exists and that the user running the paperless service can read/write its contents before you start Paperless.

  Don't change this when using docker, as it only changes the path within the container. Change the local consumption directory in the docker-compose.yml file instead.

  Defaults to "../consume/", relative to the "src" directory.

#### `PAPERLESS_DATA_DIR=<path>`

  This is where paperless stores all its data (search index, SQLite database, classification model, etc).

  Defaults to "../data/", relative to the "src" directory.

#### `PAPERLESS_EMPTY_TRASH_DIR=<path>`

  When documents are deleted (e.g. after emptying the trash) the original files will be moved here instead of being removed from the filesystem. Only the original version is kept.

  This must be writeable by the user running paperless. When running inside docker, ensure that this path is within a permanent volume (such as "../media/trash") so it won't get lost on upgrades.

  Note that the directory must exist prior to using this setting.

  Defaults to empty (i.e. really delete files).

  This setting was previously named PAPERLESS_TRASH_DIR.

#### `PAPERLESS_MEDIA_ROOT=<path>`

  This is where your documents and thumbnails are stored.

  You can set this and PAPERLESS_DATA_DIR to the same folder to have paperless store all its data within the same volume.

  Defaults to "../media/", relative to the "src" directory.

#### `PAPERLESS_STATICDIR=<path>`

  Override the default STATIC_ROOT here. This is where all static files created using "collectstatic" manager command are stored.

  Unless you're doing something fancy, there is no need to override this. If this is changed, you may need to run `collectstatic` again.

  Defaults to "../static/", relative to the "src" directory.

#### `PAPERLESS_FILENAME_FORMAT=<format>`

  Changes the filenames paperless uses to store documents in the media directory. See File name handling for details.

  Default is none, which disables this feature.

#### `PAPERLESS_FILENAME_FORMAT_REMOVE_NONE=<bool>`

  Tells paperless to replace placeholders in `PAPERLESS_FILENAME_FORMAT` that would resolve to 'none' to be omitted from the resulting filename. This also holds true for directory names. See File name handling for details.

  Defaults to `false` which disables this feature.

#### `PAPERLESS_LOGGING_DIR=<path>`

  This is where paperless will store log files.

  Defaults to `PAPERLESS_DATA_DIR/log/`.

#### `PAPERLESS_NLTK_DIR=<path>`

  This is where paperless will search for the data required for NLTK processing, if you are using it. If you are using the Docker image, this should not be changed, as the data is included in the image already.

Previously, the location defaulted to `PAPERLESS_DATA_DIR/nltk`. Unless you are using this in a bare metal install or other setup, this folder is no longer needed and can be removed manually.

Defaults to `/usr/share/nltk_data`

#### `PAPERLESS_MODEL_FILE=<path>`

  This is where paperless will store the classification model.

  Warning

  The classification model uses Python's pickle serialization format. Ensure this file is only writable by the paperless user, as a maliciously crafted model file could execute arbitrary code when loaded.

  Defaults to `PAPERLESS_DATA_DIR/classification_model.pickle`.

## Logging

#### `PAPERLESS_LOGROTATE_MAX_SIZE=<num>`

  Maximum file size for log files before they are rotated, in bytes.

  Defaults to 1 MiB.

#### `PAPERLESS_LOGROTATE_MAX_BACKUPS=<num>`

  Number of rotated log files to keep.

  Defaults to 20.

## Hosting & Security

#### `PAPERLESS_SECRET_KEY=<key>`

  Required. Paperless uses this to make session tokens and sign sensitive data. Paperless will refuse to start if this is not set.

  Use any sequence of characters. The more, the better. You don't need to remember this. You can generate a suitable key with:

      python3 -c "import secrets; print(secrets.token_urlsafe(64))"

  Warning

  This setting has no default value. You must set it before starting Paperless. Existing installations that relied on the previous default value should set `PAPERLESS_SECRET_KEY` to that value to avoid invalidating existing sessions and tokens.

#### `PAPERLESS_URL=<url>`

  This setting can be used to set the three options below (ALLOWED_HOSTS, CORS_ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS). If the other options are set the values will be combined with this one. Do not include a trailing slash. E.g. https://paperless.domain.com

  Defaults to empty string, leaving the other settings unaffected.

  Note

  This value cannot contain a path (e.g. domain.com/path), even if you are installing paperless-ngx at a subpath.

#### `PAPERLESS_CSRF_TRUSTED_ORIGINS=<comma-separated-list>`

  A list of trusted origins for unsafe requests (e.g. POST). As of Django 4.0 this is required to access the Django admin via the web. See the Django project documentation on the settings

  Can also be set using PAPERLESS_URL (see above).

  Defaults to empty string, which does not add any origins to the trusted list.

#### `PAPERLESS_ALLOWED_HOSTS=<comma-separated-list>`

  If you're planning on putting Paperless on the open internet, then you really should set this value to the domain name you're using. Failing to do so leaves you open to HTTP host header attacks. You can read more about this in the Django project's documentation

  Just remember that this is a comma-separated list, so "example.com" is fine, as is "example.com,www.example.com", but NOT " example.com" or "example.com,"

  Can also be set using PAPERLESS_URL (see above).

  "localhost" is always allowed for docker healthcheck

  Defaults to "*", which is all hosts.

#### `PAPERLESS_CORS_ALLOWED_HOSTS=<comma-separated-list>`

  You need to add your servers to the list of allowed hosts that can do CORS calls. Set this to your public domain name.

  Can also be set using PAPERLESS_URL (see above).

  Defaults to "http://localhost:8000".

#### `PAPERLESS_TRUSTED_PROXIES=<comma-separated-list>`

  This may be needed to prevent IP address spoofing if you are using e.g. fail2ban with log entries for failed authorization attempts. Value should be IP address(es).

  By default, this setting also controls allauth's trusted proxy count, which is set to the number of proxies listed here. Override that default with `PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT` when the list length does not match the number of proxy hops.

  Defaults to empty string.

#### `PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT=<integer>`

  Sets allauth's `ALLAUTH_TRUSTED_PROXY_COUNT`. This is the number of trusted proxy hops represented in each `X-Forwarded-For` header, not the number of IP addresses through which those proxies may be reached. For example, a single dual-stack proxy is one hop even when its IPv4 and IPv6 addresses are both listed in `PAPERLESS_TRUSTED_PROXIES`.

  Only trust `X-Forwarded-For` when untrusted clients cannot connect directly to Paperless-ngx.

  Defaults to the number of entries in `PAPERLESS_TRUSTED_PROXIES`.

#### `PAPERLESS_ALLAUTH_TRUSTED_CLIENT_IP_HEADER=<header-name>`

  Sets allauth's `ALLAUTH_TRUSTED_CLIENT_IP_HEADER`. Use this when your reverse proxy sets a dedicated header for the real client IP instead of `X-Forwarded-For`, for example `X-Real-IP` (nginx) or `CF-Connecting-IP` (Cloudflare). When set, this takes precedence over `PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT`.

  Defaults to none.

#### `PAPERLESS_FORCE_SCRIPT_NAME=<path>`

  To host paperless under a subpath url like example.com/paperless you set this value to /paperless. No trailing slash!

  Defaults to none, which hosts paperless at "/".

#### `PAPERLESS_STATIC_URL=<path>`

  Override the STATIC_URL here. Unless you're hosting Paperless off a specific path like /paperless/, you probably don't need to change this. If you do change it, be sure to include the trailing slash.

  Defaults to "/static/".

  Note

  When hosting paperless behind a reverse proxy like Traefik or Nginx at a subpath e.g. example.com/paperlessngx you will also need to set `PAPERLESS_FORCE_SCRIPT_NAME` (see above).

#### `PAPERLESS_AUTO_LOGIN_USERNAME=<username>`

  Specify a username here so that paperless will automatically perform login with the selected user.

  Danger

  Do not use this when exposing paperless on the internet. There are no checks in place that would prevent you from doing this.

  Defaults to none, which disables this feature.

#### `PAPERLESS_ADMIN_USER=<username>`

  If this environment variable is specified, Paperless automatically creates a superuser with the provided username at start. This is useful in cases where you can not run the `createsuperuser` command separately, such as Kubernetes or AWS ECS.

  Requires PAPERLESS_ADMIN_PASSWORD be set.

  Note

  This will not change an existing [super]user's password, nor will it recreate a user that already exists. You can leave this throughout the lifecycle of the containers.

#### `PAPERLESS_ADMIN_MAIL=<email>`

  (Optional) Specify superuser email address. Only used when PAPERLESS_ADMIN_USER is set.

  Defaults to `root@localhost`.

#### `PAPERLESS_ADMIN_PASSWORD=<password>`

  Only used when PAPERLESS_ADMIN_USER is set. This will be the password of the automatically created superuser.

#### `PAPERLESS_COOKIE_PREFIX=<str>`

  Specify a prefix that is added to the cookies used by paperless to identify the currently logged in user. This is useful for when you're running two instances of paperless on the same host.

  After changing this, you will have to login again.

  Defaults to `""`, which does not alter the cookie names.

#### `PAPERLESS_ENABLE_HTTP_REMOTE_USER=<bool>`

  Allows authentication via HTTP_REMOTE_USER which is used by some SSO applications.

  Warning

  This will allow authentication by simply adding a `Remote-User: <username>` header to a request. Use with care! You especially must ensure that any such header is not passed from external requests to your reverse-proxy to paperless (that would effectively bypass all authentication).

  If you're exposing paperless to the internet directly (i.e. without a reverse proxy), do not use this.

  Also see the warning in the official documentation.

  Defaults to "false" which disables this feature.

#### `PAPERLESS_ENABLE_HTTP_REMOTE_USER_API=<bool>`

  Allows authentication via HTTP_REMOTE_USER directly against the API

  Warning

  See the warning above about securing your installation when using remote user header authentication. This setting is separate from `PAPERLESS_ENABLE_HTTP_REMOTE_USER` to avoid introducing a security vulnerability to existing reverse proxy setups. As above, ensure that your reverse proxy does not simply pass the `Remote-User` header from the internet to paperless.

  Defaults to "false" which disables this feature.

#### `PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME=<str>`

  If "PAPERLESS_ENABLE_HTTP_REMOTE_USER" or `PAPERLESS_ENABLE_HTTP_REMOTE_USER_API` are enabled, this property allows to customize the name of the HTTP header from which the authenticated username is extracted. Values are in terms of HttpRequest.META. Thus, the configured value must start with `HTTP*` followed by the normalized actual header name.

  Defaults to "HTTP_REMOTE_USER".

#### `PAPERLESS_LOGOUT_REDIRECT_URL=<str>`

  URL to redirect the user to after a logout. This can be used together with PAPERLESS_ENABLE_HTTP_REMOTE_USER and SSO to redirect the user back to the SSO application's logout page to complete the logout process.

  Defaults to None, which disables this feature.

#### `PAPERLESS_USE_X_FORWARD_HOST=<bool>`

  Configures the Django setting USE_X_FORWARDED_HOST which may be needed for hosting behind a proxy.

  Defaults to False

#### `PAPERLESS_USE_X_FORWARD_PORT=<bool>`

  Configures the Django setting USE_X_FORWARDED_PORT which may be needed for hosting behind a proxy.

  Defaults to False

#### `PAPERLESS_PROXY_SSL_HEADER=<json-list>`

  Configures the Django setting SECURE_PROXY_SSL_HEADER which may be needed for hosting behind a proxy. The two values in the list will form the tuple of HTTP header/value expected by Django, eg `'["HTTP_X_FORWARDED_PROTO", "https"]'`.

  Defaults to None

Warning

Settings this value has security implications. Read the Django documentation and be sure you understand its usage before setting it.

#### `PAPERLESS_EMAIL_CERTIFICATE_LOCATION=<path>`

  Configures an additional SSL certificate file containing a certificate or certificate chain which should be trusted for validating SSL connections against mail providers. This is for use with self-signed certificates against local IMAP servers.

  Defaults to None.

Warning

Settings this value has security implications for the security of your email. Understand what it does and be sure you need to before setting.

### Authentication & SSO

#### `PAPERLESS_ACCOUNT_ALLOW_SIGNUPS=<bool>`

  Allow users to signup for a new Paperless-ngx account.

  Defaults to False

#### `PAPERLESS_ACCOUNT_DEFAULT_GROUPS=<comma-separated-list>`

  A list of group names that users will be added to when they sign up for a new account. Groups listed here must already exist.

  Defaults to None

#### `PAPERLESS_SOCIALACCOUNT_PROVIDERS=<json>`

  This variable is used to setup login and signup via social account providers which are compatible with django-allauth. See the corresponding django-allauth documentation for a list of provider configurations. You will also need to include the relevant Django 'application' inside the PAPERLESS_APPS setting to activate that specific authentication provider (e.g. `allauth.socialaccount.providers.openid_connect` for the OIDC Connect provider).

  For OpenID Connect providers, set `settings.token_auth_method` if your identity provider requires a specific token endpoint authentication method.

  Defaults to None, which does not enable any third party authentication systems.

#### `PAPERLESS_SOCIAL_AUTO_SIGNUP=<bool>`

  Attempt to signup the user using retrieved email, username etc from the third party authentication system. See the corresponding django-allauth documentation

  Defaults to False

#### `PAPERLESS_SOCIALACCOUNT_ALLOW_SIGNUPS=<bool>`

  Allow users to signup for a new Paperless-ngx account using any setup third party authentication systems.

  Defaults to True

#### `PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS=<bool>`

  Sync groups from the third party authentication system (e.g. OIDC) to Paperless-ngx. When enabled, users will be added or removed from groups based on their group membership in the third party authentication system. Groups must already exist in Paperless-ngx and have the same name as in the third party authentication system. Groups are updated upon logging in via the third party authentication system, see the corresponding django-allauth documentation.

  In order to pass groups from the authentication system you will need to update your PAPERLESS_SOCIALACCOUNT_PROVIDERS setting by adding a top-level "SCOPES" setting which includes "groups", or the custom groups claim configured in `PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS_CLAIM` e.g.:

      {"openid_connect":{"SCOPE": ["openid","profile","email","groups"]...

  Defaults to False

#### `PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS_CLAIM=<str>`

  Allows you to define a custom groups claim. See PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS which is required for this setting to take effect.

  Defaults to "groups"

#### `PAPERLESS_SOCIAL_ACCOUNT_DEFAULT_GROUPS=<comma-separated-list>`

  A list of group names that users who signup via social accounts will be added to upon signup. Groups listed here must already exist. If both the PAPERLESS_ACCOUNT_DEFAULT_GROUPS setting and this setting are used, the user will be added to both sets of groups.

  Defaults to None

#### `PAPERLESS_ACCOUNT_DEFAULT_HTTP_PROTOCOL=<string>`

  The protocol used when generating URLs, e.g. login callback URLs. See the corresponding django-allauth documentation

  Defaults to 'https'

#### `PAPERLESS_ACCOUNT_EMAIL_VERIFICATION=<string>`

  Determines whether email addresses are verified during signup (as performed by Django allauth). See the relevant paperless settings and the allauth docs

  Defaults to 'optional'

Note

If you do not have a working email server set up this will be set to 'none'.

#### `PAPERLESS_ACCOUNT_EMAIL_UNKNOWN_ACCOUNTS=<bool>`

  See the relevant django-allauth documentation

  Defaults to True (from allauth)

#### `PAPERLESS_DISABLE_REGULAR_LOGIN=<bool>`

  Disables the regular frontend username / password login, i.e. once you have setup SSO. Note that this setting does not disable the Django admin login nor logging in with local credentials via the API. To prevent access to the Django admin, consider blocking `/admin/` in your web server or reverse proxy configuration.

  You can optionally also automatically redirect users to the SSO login with PAPERLESS_REDIRECT_LOGIN_TO_SSO

  Defaults to False

#### `PAPERLESS_REDIRECT_LOGIN_TO_SSO=<bool>`

  When this setting is enabled users will automatically be redirected (using javascript) to the first SSO provider login. You may still want to disable the frontend login form for clarity.

  Defaults to False

#### `PAPERLESS_ACCOUNT_SESSION_REMEMBER=<bool>`

  If false, sessions will expire at browser close, if true will use `PAPERLESS_SESSION_COOKIE_AGE` for expiration. See the corresponding django-allauth documentation

  Defaults to True

#### `PAPERLESS_SESSION_COOKIE_AGE=<int>`

  Login session cookie expiration. Applies if `PAPERLESS_ACCOUNT_SESSION_REMEMBER` is enabled. See the corresponding django documentation

  Defaults to 1209600 (2 weeks)

#### `PAPERLESS_TOKEN_THROTTLE_RATE=<rate>`

  Rate limit for the API token authentication endpoint (`/api/token/`), used to mitigate brute-force login attempts. Uses Django REST Framework's throttle rate format, e.g. `5/min`, `100/hour`, `1000/day`.

  Defaults to `5/min`

## OCR settings

Paperless uses OCRmyPDF for performing OCR on documents and images. Paperless uses sensible defaults for most settings, but all of them can be configured to your needs.

#### `PAPERLESS_OCR_LANGUAGE=<lang>`

  Customize the language that paperless will attempt to use when parsing documents.

  It should be a 3-letter code, see the list of languages Tesseract supports.

  Set this to the language most of your documents are written in.

  This can be a combination of multiple languages such as `deu+eng`, in which case Tesseract will use whatever language matches best. Keep in mind that Tesseract uses much more CPU time with multiple languages enabled.

  If you are including languages that are not installed by default, you will need to also set `PAPERLESS_OCR_LANGUAGES` for docker deployments or install the tesseract language packages manually for bare metal installations.

  Defaults to "eng".

  Note

  If your language contains a '-' such as chi-sim, you must use `chi_sim`.

#### `PAPERLESS_OCR_MODE=<mode>`

  Tell paperless when and how to perform ocr on your documents. Four modes are available:

  - `auto` (default): Paperless detects whether a document already has embedded text via pdftotext. If sufficient text is found, OCR is skipped for that document (`--skip-text`). If no text is present, OCR runs normally. This is the safest option for mixed document collections.

  - `redo`: Paperless will OCR all pages of your documents and attempt to replace any existing text layers with new text. This will be useful for documents from scanners that already performed OCR with insufficient results. It will also perform OCR on purely digital documents.

    This option may fail on some documents that have features that cannot be removed, such as forms. In this case, the text from the document is used instead.

  - `force`: Paperless rasterizes your documents, converting any text into images and puts the OCRed text on top. This works for all documents, however, the resulting document may be significantly larger and text won't appear as sharp when zoomed in.

  - `off`: Paperless never invokes the OCR engine. For PDFs, text is extracted via pdftotext only. For image documents, text will be empty. Archive file generation still works via format conversion (no Tesseract or Ghostscript required).

  The default is `auto`.

  For the `redo` and `force` modes, read more about OCR behaviour in the OCRmyPDF documentation.

#### `PAPERLESS_ARCHIVE_FILE_GENERATION=<mode>`

  Controls when paperless creates a PDF/A archive version of your documents. Archive files are stored alongside the original and are used for display in the web interface.

  - `auto` (default): Produce archives for scanned or image-based documents. Skip archive generation for born-digital PDFs that already contain embedded text. This is the recommended setting for mixed document collections.
  - `always`: Always produce a PDF/A archive when the parser supports it, regardless of whether the document already has text.
  - `never`: Never produce an archive. Only the original file is stored. Saves disk space but the web viewer will display the original file directly.

  Behaviour by file type and mode (`auto` column shows the default):

  Document type | `never` | `auto` (default) | `always`
  --- | --- | --- | ---
  Scanned image (TIFF, JPEG) | No | Yes | Yes
  Image-based PDF | No | Yes (no embedded text) | Yes
  Born-digital PDF | No | No (has embedded text, optionally confirmed by tag) | Yes
  Plain text, email, HTML | No | No | No
  DOCX / ODT (via Tika) | Yes* | Yes* | Yes*

  * Tika always produces a PDF rendition for display; this counts as the archive regardless of the setting.

  Note

  This setting applies to the built-in Tesseract parser. Parsers that must always convert documents to PDF for display (e.g. DOCX, ODT via Tika) will produce a PDF regardless of this setting.

  Note

  The remote OCR parser (Azure AI) always produces a searchable PDF and stores it as the archive copy, regardless of this setting. `ARCHIVE_FILE_GENERATION=never` has no effect when the remote parser handles a document.

#### `PAPERLESS_OCR_CLEAN=<mode>`

  Tells paperless to use `unpaper` to clean any input document before sending it to tesseract. This uses more resources, but generally results in better OCR results. The following modes are available:

  - `clean`: Apply unpaper.
  - `clean-final`: Apply unpaper, and use the cleaned images to build the output file instead of the original images.
  - `none`: Do not apply unpaper.

  Defaults to `clean`.

  Note

  `clean-final` is incompatible with ocr mode `redo`. When both `clean-final` and the ocr mode `redo` is configured, `clean` is used instead.

#### `PAPERLESS_OCR_DESKEW=<bool>`

  Tells paperless to correct skewing (slight rotation of input images mainly due to improper scanning)

  Defaults to `true`, which enables this feature.

  Note

  Deskewing is incompatible with ocr mode `redo`. Deskewing will get disabled automatically if `redo` is used as the ocr mode.

#### `PAPERLESS_OCR_ROTATE_PAGES=<bool>`

  Tells paperless to correct page rotation (90°, 180° and 270° rotation).

  If you notice that paperless is not rotating incorrectly rotated pages (or vice versa), try adjusting the threshold up or down (see below).

  Defaults to `true`, which enables this feature.

#### `PAPERLESS_OCR_ROTATE_PAGES_THRESHOLD=<num>`

  Adjust the threshold for automatic page rotation by `PAPERLESS_OCR_ROTATE_PAGES`. This is an arbitrary value reported by tesseract. "15" is a very conservative value, whereas "2" is a very aggressive option and will often result in correctly rotated pages being rotated as well.

  Defaults to "12".

#### `PAPERLESS_OCR_OUTPUT_TYPE=<type>`

  Specify the type of PDF documents that paperless should produce.

  - `pdf`: Modify the PDF document as little as possible.
  - `pdfa`: Convert PDF documents into PDF/A-2b documents, which is a subset of the entire PDF specification and meant for storing documents long term.
  - `pdfa-1`, `pdfa-2`, `pdfa-3` to specify the exact version of PDF/A you wish to use.

  If not specified, `pdfa` is used. Remember that paperless also keeps the original input file as well as the archived version.

#### `PAPERLESS_OCR_PAGES=<num>`

  Tells paperless to use only the specified amount of pages for OCR. Documents with less than the specified amount of pages get OCR'ed completely.

  Specifying 1 here will only use the first page.

  The value must be greater than or equal to 1 to be used.

  When combined with `PAPERLESS_OCR_MODE=redo` or `PAPERLESS_OCR_MODE=force`, paperless will not modify any text it finds on excluded pages and copy it verbatim.

  Defaults to unset, which disables this feature and always uses all pages.

#### `PAPERLESS_OCR_IMAGE_DPI=<num>`

  Paperless will OCR any images you put into the system and convert them into PDF documents. This is useful if your scanner produces images. In order to do so, paperless needs to know the DPI of the image. Most images from scanners will have this information embedded and paperless will detect and use that information. In case this fails, it uses this value as a fallback.

  Set this to the DPI your scanner produces images at.

  Defaults to unset, which will automatically calculate image DPI so that the produced PDF documents are A4 sized.

#### `PAPERLESS_OCR_MAX_IMAGE_PIXELS=<num>`

  Paperless will raise a warning when OCRing images which are over this limit and will not OCR images which are more than twice this limit. Note this does not prevent the document from being consumed, but could result in missing text content.

  If unset, will default to the value determined by Pillow.

  Setting this value to 0 will entirely disable the limit. See the below warning.

  Note

  Increasing this limit could cause Paperless to consume additional resources when consuming a file. Be sure you have sufficient system resources.

  Warning

  The limit is intended to prevent malicious files from consuming system resources and causing crashes and other errors. Only change this value if you are certain your documents are not malicious and you need the text which was not OCRed

#### `PAPERLESS_OCR_COLOR_CONVERSION_STRATEGY=<RGB>`

  Controls the Ghostscript color conversion strategy when creating the archive file. This setting will only be utilized if the output is a version of PDF/A.

  Valid options are CMYK, Gray, LeaveColorUnchanged, RGB or UseDeviceIndependentColor.

  You can find more on the settings here in the Ghostscript documentation.

  Warning

  Utilizing some of the options may result in errors when creating archive files from PDFs.

#### `PAPERLESS_OCR_USER_ARGS=<json>`

  OCRmyPDF offers many more options. Use this parameter to specify any additional arguments you wish to pass to OCRmyPDF. Since Paperless uses the API of OCRmyPDF, you have to specify these in a format that can be passed to the API. See the API reference of OCRmyPDF for valid parameters. All command line options are supported, but they use underscores instead of dashes.

  Warning

  Paperless has been tested to work with the OCR options provided above. There are many options that are incompatible with each other, so specifying invalid options may prevent paperless from consuming any documents. Use with caution!

  Specify arguments as a JSON dictionary. Keep note of lower case booleans and double quoted parameter names and strings. Examples:

      {"deskew": true, "optimize": 3, "unpaper_args": "--pre-rotate 90"}

## Software tweaks

#### `PAPERLESS_TASK_WORKERS=<num>`

  Paperless does multiple things in the background: Maintain the search index, maintain the automatic matching algorithm, check emails, consume documents, etc. This variable specifies how many things it will do in parallel.

  Defaults to 1

#### `PAPERLESS_THREADS_PER_WORKER=<num>`

  Furthermore, paperless uses multiple threads when consuming documents to speed up OCR. This variable specifies how many pages paperless will process in parallel on a single document.

  Warning

  Ensure that the product

  `PAPERLESS_TASK_WORKERS * PAPERLESS_THREADS_PER_WORKER`

  does not exceed your CPU core count or else paperless will be extremely slow. If you want paperless to process many documents in parallel, choose a high worker count. If you want paperless to process very large documents faster, use a higher thread per worker count.

  If unset, paperless uses `max(floor(cpu_count / PAPERLESS_TASK_WORKERS), 1)` threads per worker. The idea behind this is that as long as there are enough cores, the total number of threads should less than or equal to the total number of (logical) CPU cores.

#### `PAPERLESS_WORKER_TIMEOUT=<num>`

  Machines with few cores or weak ones might not be able to finish OCR on large documents within the default 1800 seconds. So extending this timeout may prove to be useful on weak hardware setups.

#### `PAPERLESS_TIME_ZONE=<timezone>`

  Set the time zone here. See more details on why and how to set it in the Django project documentation for details on how to set it.

  Defaults to UTC.

#### `PAPERLESS_ENABLE_NLTK=<bool>`

  Enables or disables the advanced natural language processing used during automatic classification. If disabled, paperless will still perform some basic text pre-processing before matching.

  See also `PAPERLESS_NLTK_DIR`.

  Defaults to true, enabling the feature.

#### `PAPERLESS_DATE_PARSER_LANGUAGES=<lang>`

  Specifies which language Paperless should use when parsing dates from documents.
  This should be a language code supported by the dateparser library, for example: "en", or a combination such as "en+de". Locales are also supported (e.g., "en-AU"). Multiple languages can be combined using "+", for example: "en+de" or "en-AU+de". For valid values, refer to the list of supported languages and locales in the dateparser documentation.

  Set this to match the languages in which most of your documents are written.

  If not set, Paperless will attempt to infer the language(s) from the OCR configuration (`PAPERLESS_OCR_LANGUAGE`).

  Note

  This format differs from the `PAPERLESS_OCR_LANGUAGE` setting, which uses ISO 639-2 codes (3 letters, e.g., "eng+deu" for Tesseract OCR).

#### `PAPERLESS_EMAIL_TASK_CRON=<cron expression>`

  Configures the scheduled email fetching frequency. The value should be a valid crontab(5) expression describing when to run.

  If set to the string "disable", no emails will be fetched automatically.

  Defaults to `*/10 * * * *` or every ten minutes.

#### `PAPERLESS_TRAIN_TASK_CRON=<cron expression>`

  Configures the scheduled automatic classifier training frequency. The value should be a valid crontab(5) expression describing when to run.

  If set to the string "disable", the classifier will not be trained automatically.

  Defaults to `5 */1 * * *` or every hour at 5 minutes past the hour.

#### `PAPERLESS_INDEX_TASK_CRON=<cron expression>`

  Configures the scheduled search index update frequency. The value should be a valid crontab(5) expression describing when to run.

  If set to the string "disable", the search index will not be automatically updated.

  Defaults to `0 0 * * *` or daily at midnight.

#### `PAPERLESS_SEARCH_LANGUAGE=<language>`

  Sets the stemmer language for the full-text search index. Stemming improves recall by matching word variants (e.g. "running" matches "run"). Changing this setting causes the index to be rebuilt automatically on next startup. An invalid value raises an error at startup.
  Use the ISO 639-1 two-letter code (e.g. `en`, `de`, `fr`). Lowercase full names (e.g. `english`, `german`, `french`) are also accepted. The capitalized names shown in the Tantivy Language enum documentation are not valid — use the lowercase equivalent.

  If not set, paperless infers the language from `PAPERLESS_OCR_LANGUAGE`. If the OCR language has no Tantivy stemmer equivalent, stemming is disabled.

  Defaults to unset (inferred from `PAPERLESS_OCR_LANGUAGE`).

#### `PAPERLESS_ADVANCED_FUZZY_SEARCH_THRESHOLD=<float>`

  When set to a float value, approximate/fuzzy matching is applied alongside exact matching. Fuzzy results rank below exact matches. A value of `0.5` is a reasonable starting point. Leave unset to disable fuzzy matching entirely.

  Defaults to unset (disabled).

#### `PAPERLESS_SANITY_TASK_CRON=<cron expression>`

  Configures the scheduled sanity checker frequency. The value should be a valid crontab(5) expression describing when to run.

  If set to the string "disable", the sanity checker will not run automatically.

  Defaults to `30 0 * * sun` or Sunday at 30 minutes past midnight.

#### `PAPERLESS_WORKFLOW_SCHEDULED_TASK_CRON=<cron expression>`

  Configures the scheduled workflow check frequency. The value should be a valid crontab(5) expression describing when to run.

  If set to the string "disable", scheduled workflows will not run.

  Defaults to `5 */1 * * *` or every hour at 5 minutes past the hour.

#### `PAPERLESS_ENABLE_COMPRESSION=<bool>`

  Enables compression of the responses from the webserver.

  Defaults to true, enabling compression.

  Note

  If you are using a proxy such as nginx, it is likely more efficient to enable compression in your proxy configuration rather than the webserver

#### `PAPERLESS_CONVERT_MEMORY_LIMIT=<num>`

  On smaller systems, or even in the case of Very Large Documents, the consumer may explode, complaining about how it's "unable to extend pixel cache". In such cases, try setting this to a reasonably low value, like 32. The default is to use whatever is necessary to do everything without writing to disk, and units are in megabytes.

  For more information on how to use this value, you should search the web for "MAGICK_MEMORY_LIMIT".

  Defaults to 0, which disables the limit.

#### `PAPERLESS_CONVERT_TMPDIR=<path>`

  Similar to the memory limit, if you've got a small system and your OS mounts /tmp as tmpfs, you should set this to a path that's on a physical disk, like /home/your_user/tmp or something. ImageMagick will use this as scratch space when crunching through very large documents.

  For more information on how to use this value, you should search the web for "MAGICK_TMPDIR".

  Default is none, which disables the temporary directory.

#### `PAPERLESS_APPS=<string>`

  A comma-separated list of Django apps to be included in Django's `INSTALLED_APPS`. This setting should be used with caution!

  Defaults to None, which does not add any additional apps.

#### `PAPERLESS_MAX_IMAGE_PIXELS=<number>`

  Configures the maximum size of an image PIL will allow to load without warning or error.

  If unset, will default to the value determined by Pillow.

  Defaults to None, which does change the limit

  Warning

  This limit is designed to prevent denial of service from malicious files. It should only be raised or disabled in certain circumstances and with great care.

## Document Consumption

#### `PAPERLESS_CONSUMER_DISABLE`

  If set (to anything), this completely disables the directory-based consumer in docker. If you don't plan to consume documents via the consumption directory, you can disable the consumer to save resources.

#### `PAPERLESS_CONSUMER_DELETE_DUPLICATES=<bool>`

  As of version 3.0 Paperless-ngx allows duplicate documents to be consumed by default, except when this setting is enabled. When enabled, Paperless will check if a document with the same hash already exists in the system and delete the duplicate file from the consumption directory without consuming it.

  Defaults to false.

#### `PAPERLESS_CONSUMER_RECURSIVE=<bool>`

  Enable recursive watching of the consumption directory. Paperless will then pickup files from files in subdirectories within your consumption directory as well.

  Defaults to false.

#### `PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=<bool>`

  Set the names of subdirectories as tags for consumed files. E.g. `<CONSUMPTION_DIR>/foo/bar/file.pdf` will add the tags "foo" and "bar" to the consumed file. Paperless will create any tags that don't exist yet.

  This is useful for sorting documents with certain tags such as `car` or `todo` prior to consumption. These folders won't be deleted.

  PAPERLESS_CONSUMER_RECURSIVE must be enabled for this to work.

  Defaults to false.

#### `PAPERLESS_CONSUMER_IGNORE_PATTERNS=<json>`

  Additional regex patterns for files to ignore in the consumption directory. Patterns are matched against filenames only (not full paths) using Python's `re.match()`, which anchors at the start of the filename.

  See the watchfiles documentation

  This setting is for additional patterns beyond the built-in defaults. Common system files and directories are already ignored automatically. The patterns will be compiled via Python's standard `re` module.

  Example custom patterns:

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

  This would ignore:

  - Files starting with `temp_` (e.g., `temp_scan.pdf`)
  - Files ending with `.bak` (e.g., `document.pdf.bak`)
  - Files starting with `~` (e.g., `~$document.docx`)

  Defaults to `[]` (empty list, uses only built-in defaults).

  The default ignores are `[.DS_Store, .DS_STORE, ._*, desktop.ini, Thumbs.db]` and cannot be overridden.

#### `PAPERLESS_CONSUMER_IGNORE_DIRS=<json>`

  Additional directory names to ignore in the consumption directory. Directories matching these names (and all their contents) will be skipped.

  This setting is for additional directories beyond the built-in defaults. Matching is done by directory name only, not full path.

  Example:

      ["temp", "incoming", ".hidden"]

  Defaults to `[]` (empty list, uses only built-in defaults).

  The default ignores are `[.stfolder, .stversions, .localized, @eaDir, .Spotlight-V100, .Trashes, __MACOSX]` and cannot be overridden.

#### `PAPERLESS_PRE_CONSUME_SCRIPT=<filename>`

  After some initial validation, Paperless can trigger an arbitrary script if you like before beginning consumption. This script will be provided data for it to work with via the environment.

  For more information, take a look at pre-consumption script.

  The default is blank, which means nothing will be executed.

#### `PAPERLESS_POST_CONSUME_SCRIPT=<filename>`

  After a document is consumed, Paperless can trigger an arbitrary script if you like. This script will be provided data for it to work with via the environment.

  For more information, take a look at Post-consumption script.

  The default is blank, which means nothing will be executed.

#### `PAPERLESS_FILENAME_DATE_ORDER=<format>`

  Paperless will check the document text for document date information. Use this setting to enable checking the document filename for date information. The date order can be set to any option as specified in https://dateparser.readthedocs.io/en/latest/settings.html#date-order. The filename will be checked first, and if nothing is found, the document text will be checked as normal.

  A date in a filename must have some separators (`.`, `,`, `-`, `/`, etc) for it to be parsed.

  Defaults to none, which disables this feature.

#### `PAPERLESS_NUMBER_OF_SUGGESTED_DATES=<num>`

  Paperless searches an entire document for dates. The first date found will be used as the initial value for the created date. When this variable is greater than 0 (or left to its default value), paperless will also suggest other dates found in the document, up to a maximum of this setting. Note that duplicates will be removed, which can result in fewer dates displayed in the frontend than this setting value.

  The task to find all dates can be time-consuming and increases with a higher (maximum) number of suggested dates and slower hardware.

  Defaults to 3. Set to 0 to disable this feature.

#### `PAPERLESS_THUMBNAIL_FONT_NAME=<filename>`

  Paperless creates thumbnails for plain text files by rendering the content of the file on an image and uses a predefined font for that. This font can be changed here.

  Note that this won't have any effect on already generated thumbnails.

  Defaults to `/usr/share/fonts/liberation/LiberationSerif-Regular.ttf`.

#### `PAPERLESS_IGNORE_DATES=<string>`

  Paperless parses a document's creation date from filename and file content. You may specify a comma separated list of dates that should be ignored during this process. This is useful for special dates (like date of birth) that appear in documents regularly but are very unlikely to be the document's creation date.

  The date is parsed using the order specified in PAPERLESS_DATE_ORDER

  Defaults to an empty string to not ignore any dates.

#### `PAPERLESS_DATE_ORDER=<format>`

  Paperless will try to determine the document creation date from its contents. Specify the date format Paperless should expect to see within your documents.

  This option defaults to DMY which translates to day first, month second, and year last order. Characters D, M, or Y can be shuffled to meet the required order.

#### `PAPERLESS_ENABLE_GPG_DECRYPTOR=<bool>`

  Enable or disable the GPG decryptor for encrypted emails. See GPG Decryptor for more information.

  Defaults to false.

#### `PAPERLESS_CONSUMER_POLLING_INTERVAL=<num>`

  Configures how the consumer detects new files in the consumption directory.

  When set to `0` (default), paperless uses native filesystem notifications for efficient, immediate detection of new files.

  When set to a positive number, paperless polls the consumption directory at that interval in seconds. Use polling for network filesystems (NFS, SMB/CIFS) where native notifications may not work reliably.

  Defaults to 0.

#### `PAPERLESS_CONSUMER_STABILITY_DELAY=<num>`

  Sets the time in seconds that a file must remain unchanged (same size and modification time) before paperless will begin consuming it.

  Increase this value if you experience issues with files being consumed before they are fully written, particularly on slower network storage or with certain scanner quirks

  Defaults to 5.0 seconds.

## Workflow webhooks

#### `PAPERLESS_WEBHOOKS_ALLOWED_SCHEMES=<str>`

  A comma-separated list of allowed schemes for webhooks. This setting controls which URL schemes are permitted for webhook URLs.

  Defaults to `http,https`.

#### `PAPERLESS_WEBHOOKS_ALLOWED_PORTS=<str>`

  A comma-separated list of allowed ports for webhooks. This setting controls which ports are permitted for webhook URLs. For example, if you set this to `80,443`, webhooks will only be sent to URLs that use these ports.

  Defaults to empty list, which allows all ports.

#### `PAPERLESS_WEBHOOKS_ALLOW_INTERNAL_REQUESTS=<bool>`

  If set to false, webhooks cannot be sent to internal URLs (e.g., localhost).

  Defaults to true, which allows internal requests.

## Incoming Mail

#### `PAPERLESS_EMAIL_ALLOW_INTERNAL_HOSTS=<bool>`

  If set to false, incoming mail account connections are blocked when the configured IMAP hostname resolves to a non-public address (for example, localhost, link-local, or RFC1918 private ranges).

  Defaults to true, which allows internal hosts.

### Email OAuth

#### `PAPERLESS_OAUTH_CALLBACK_BASE_URL=<str>`

  The base URL for the OAuth callback. This is used to construct the full URL for the OAuth callback. This should be the URL that the Paperless instance is accessible at. If not set, defaults to the `PAPERLESS_URL` setting. At least one of these settings must be set to enable OAuth Email setup.

  Defaults to none (thus will use PAPERLESS_URL).

Note

This setting only applies to OAuth Email setup (not to the SSO setup).

#### `PAPERLESS_GMAIL_OAUTH_CLIENT_ID=<str>`

  The OAuth client ID for Gmail. This is required for Gmail OAuth Email setup. See OAuth Email Setup for more information.

  Defaults to none.

#### `PAPERLESS_GMAIL_OAUTH_CLIENT_SECRET=<str>`

  The OAuth client secret for Gmail. This is required for Gmail OAuth Email setup. See OAuth Email Setup for more information.

  Defaults to none.

#### `PAPERLESS_OUTLOOK_OAUTH_CLIENT_ID=<str>`

  The OAuth client ID for Outlook. This is required for Outlook OAuth Email setup. See OAuth Email Setup for more information.

  Defaults to none.

#### `PAPERLESS_OUTLOOK_OAUTH_CLIENT_SECRET=<str>`

  The OAuth client secret for Outlook. This is required for Outlook OAuth Email setup. See OAuth Email Setup for more information.

  Defaults to none.

### Encrypted Emails

#### `PAPERLESS_EMAIL_GNUPG_HOME=<str>`

  Optional, sets the `GNUPG_HOME` path to use with GPG decryptor for encrypted emails. See GPG Decryptor for more information. If not set, defaults to the default `GNUPG_HOME` path.

  Defaults to .

## Barcodes

#### `PAPERLESS_CONSUMER_ENABLE_BARCODES=<bool>`

  Enables the scanning and page separation based on detected barcodes. This allows for scanning and adding multiple documents per uploaded file, which are separated by one or multiple barcode pages.

  For ease of use, it is suggested to use a standardized separation page, e.g. here.

  If no barcodes are detected in the uploaded file, no page separation will happen.

  The original document will be removed and the separated pages will be saved as pdf.

  See additional information in the advanced usage documentation

  Defaults to false.

#### `PAPERLESS_CONSUMER_BARCODE_TIFF_SUPPORT=<bool>`

  Whether TIFF image files should be scanned for barcodes. This will automatically convert any TIFF image(s) to pdfs for later processing. This only has an effect, if PAPERLESS_CONSUMER_ENABLE_BARCODES has been enabled.

  Defaults to false.

#### `PAPERLESS_CONSUMER_BARCODE_STRING=<string>`

  Defines the string to be detected as a separator barcode. If paperless is used with the PATCH-T separator pages, users shouldn't change this.

  Defaults to "PATCHT"

#### `PAPERLESS_CONSUMER_BARCODE_RETAIN_SPLIT_PAGES=<bool>`

  If set to true, all pages that are split by a barcode (such as PATCHT) will be kept.

  Defaults to false.

#### `PAPERLESS_CONSUMER_ENABLE_ASN_BARCODE=<bool>`

  Enables the detection of barcodes in the scanned document and setting the ASN (archive serial number) if a properly formatted barcode is detected.

  The barcode must consist of a (configurable) prefix and the ASN to be set, for instance `ASN00123`. The content after the prefix is cleaned of non-numeric characters.

  This option is compatible with barcode page separation, since pages will be split up before reading the ASN.

  If no ASN barcodes are detected in the uploaded file, no ASN will be set. If a barcode with an existing ASN is detected, the document will not be consumed and an error logged.

  Defaults to false.

#### `PAPERLESS_CONSUMER_ASN_BARCODE_PREFIX=<string>`

  Defines the prefix that is used to identify a barcode as an ASN barcode.

  Defaults to "ASN"

#### `PAPERLESS_CONSUMER_BARCODE_UPSCALE=<float>`

  Defines the upscale factor used in barcode detection. Improves the detection of small barcodes, i.e. with a value of 1.5 by upscaling the document before the detection process. Upscaling will only take place if value is bigger than 1.0. Otherwise upscaling will not be performed to save resources. Try using in combination with PAPERLESS_CONSUMER_BARCODE_DPI set to a value higher than default.

  Defaults to 0.0

#### `PAPERLESS_CONSUMER_BARCODE_DPI=<int>`

  During barcode detection every page from a PDF document needs to be converted to an image. A dpi value can be specified in the conversion process. Default is 300. If the detection of small barcodes fails a bigger dpi value i.e. 600 can fix the issue. Try using in combination with PAPERLESS_CONSUMER_BARCODE_UPSCALE bigger than 1.0.

  Defaults to "300"

#### `PAPERLESS_CONSUMER_BARCODE_MAX_PAGES=<int>`

  Because barcode detection is a computationally-intensive operation, this setting limits the detection of barcodes to a number of first pages. If your scanner has a limit for the number of pages that can be scanned it would be sensible to set this as the limit here.

  Defaults to "0", allowing all pages to be checked for barcodes.

#### `PAPERLESS_CONSUMER_ENABLE_TAG_BARCODE=<bool>`

  Enables the detection of barcodes in the scanned document and assigns or creates tags if a properly formatted barcode is detected.

  The barcode must match one of the (configurable) regular expressions. If the barcode text contains ',' (comma), it is split into multiple barcodes which are individually processed for tagging.

  Matching is case insensitive.

  Defaults to false.

#### `PAPERLESS_CONSUMER_TAG_BARCODE_MAPPING=<json dict>`

  Defines a dictionary of filter regex and substitute expressions.

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

  A barcode is considered for tagging if the barcode text matches at least one of the provided pattern.

  If a match is found, the rule is applied. This allows very versatile reformatting and mapping of barcode pattern to tag values.

  If a tag is not found it will be created.

  Defaults to:

  `{"TAG:(.*)": "\\g<1>"}` which defines - a regex TAG:(.*) which includes barcodes beginning with TAG: followed by any text that gets stored into match group #1 and - a substitute `\\g<1>` that replaces the original barcode text by the content in match group #1. Consequently, the tag is the barcode text without its TAG: prefix.

  More examples:

  `{"ASN12.*": "JOHN", "ASN13.*": "SMITH"}` for example maps - ASN12nnnn barcodes to the tag JOHN and - ASN13nnnn barcodes to the tag SMITH.

  `{"T-J": "JOHN", "T-S": "SMITH", "T-D": "DOE"}` directly maps - T-J barcodes to the tag JOHN, - T-S barcodes to the tag SMITH and - T-D barcodes to the tag DOE.

  Please refer to the Python regex documentation for more information.

#### `PAPERLESS_CONSUMER_TAG_BARCODE_SPLIT=<bool>`

  Enables splitting of documents on tag barcodes, similar to how ASN barcodes work.

  When enabled, documents will be split into separate PDFs at pages containing tag barcodes that match the configured `PAPERLESS_CONSUMER_TAG_BARCODE_MAPPING` patterns. The page with the tag barcode will be retained in the new document.

  Each split document will have the detected tags assigned to it.

  This only has an effect if `PAPERLESS_CONSUMER_ENABLE_TAG_BARCODE` is also enabled.

  Defaults to false.

## Audit Trail

#### `PAPERLESS_AUDIT_LOG_ENABLED=<bool>`

  Enables the audit trail for documents, document types, correspondents, and tags.

  Defaults to true.

## Collate Double-Sided Documents

#### `PAPERLESS_CONSUMER_ENABLE_COLLATE_DOUBLE_SIDED=<bool>`

  Enables automatic collation of two single-sided scans into a double-sided document.

  This is useful if you have an automatic document feeder that only supports single-sided scans, but you need to scan a double-sided document. If your ADF supports double-sided scans natively, you do not need this feature.

  `PAPERLESS_CONSUMER_RECURSIVE` must be enabled for this to work.

  For more information, read the corresponding section in the advanced documentation.

  Defaults to false.

#### `PAPERLESS_CONSUMER_COLLATE_DOUBLE_SIDED_SUBDIR_NAME=<str>`

  The name of the subdirectory that the collate feature expects documents to arrive.

  This only has an effect if `PAPERLESS_CONSUMER_ENABLE_COLLATE_DOUBLE_SIDED` has been enabled. Note that Paperless will not automatically create the directory.

  Defaults to "double-sided".

#### `PAPERLESS_CONSUMER_COLLATE_DOUBLE_SIDED_TIFF_SUPPORT=<bool>`

  Whether TIFF image files should be supported when collating documents. This will automatically convert any TIFF image(s) to pdfs for later processing. This only has an effect if `PAPERLESS_CONSUMER_ENABLE_COLLATE_DOUBLE_SIDED` has been enabled.

  Defaults to false.

## Trash

#### `PAPERLESS_EMPTY_TRASH_DELAY=<num>`

  Sets how long in days documents remain in the 'trash' before they are permanently deleted.

  Defaults to 30 days, minimum of 1 day.

#### `PAPERLESS_EMPTY_TRASH_TASK_CRON=<cron expression>`

  Configures the schedule to empty the trash of expired deleted documents.

  Defaults to `0 1 * * *`, once per day.

## Share links

#### `PAPERLESS_SHARE_LINK_BUNDLE_CLEANUP_CRON=<cron expression>`

  Controls how often Paperless-ngx removes expired share link bundles (and their generated ZIP archives).

  If set to the string "disable", expired bundles are not cleaned up automatically.

  Defaults to `0 2 * * *`, once per day at 02:00.

## Binaries

There are a few external software packages that Paperless expects to find on your system when it starts up. Unless you've done something creative with their installation, you probably won't need to edit any of these. However, if you've installed these programs somewhere where simply typing the name of the program doesn't automatically execute it (ie. the program isn't in your $PATH), then you'll need to specify the literal path for that program.

#### `PAPERLESS_CONVERT_BINARY=<path>`

  Defaults to "convert".

#### `PAPERLESS_GS_BINARY=<path>`

  Defaults to "gs".

## Docker-specific options

These options don't have any effect in `paperless.conf`. These options adjust the behavior of the docker container. Configure these in `docker-compose.env`.

#### `PAPERLESS_WEBSERVER_WORKERS=<num>`

  The number of worker processes the webserver should spawn. More worker processes usually result in the front end to load data much quicker. However, each worker process also loads the entire application into memory separately, so increasing this value will increase RAM usage.

  Defaults to 1.

  Note

  This option may also be set with `GRANIAN_WORKERS` and this option may be removed in the future

#### `PAPERLESS_BIND_ADDR=<ip address>`

  The IP address the webserver will listen on inside the container. There are special setups where you may need to configure this value to restrict the Ip address or interface the webserver listens on.

  Defaults to `::`, meaning all interfaces, including IPv6.

  Note

  This option may also be set with `GRANIAN_HOST` and this option may be removed in the future

#### `PAPERLESS_PORT=<port>`

  The port number the webserver will listen on inside the container. There are special setups where you may need this to avoid collisions with other services (like using podman with multiple containers in one pod).

  Don't change this when using Docker. To change the port the webserver is reachable outside of the container, instead refer to the "ports" key in `docker-compose.yml`.

  Defaults to 8000.

  Note

  This option may also be set with `GRANIAN_PORT` and this option may be removed in the future

#### `USERMAP_UID=<uid>`

  The ID of the paperless user in the container. Set this to your actual user ID on the host system, which you can get by executing

      id -u

  Paperless will change ownership on its folders to this user, so you need to get this right in order to be able to write to the consumption directory.

  Defaults to 1000.

#### `USERMAP_GID=<gid>`

  The ID of the paperless Group in the container. Set this to your actual group ID on the host system, which you can get by executing

      id -g

  Paperless will change ownership on its folders to this group, so you need to get this right in order to be able to write to the consumption directory.

  Defaults to 1000.

#### `PAPERLESS_OCR_LANGUAGES=<list>`

  Additional OCR languages to install. By default, paperless comes with English, German, Italian, Spanish and French. If your language is not in this list, install additional languages with this configuration option. You will need to find the right LangCodes but note that tesseract-ocr-* package names do not always correspond with the language codes e.g. "chi_tra" should be specified as "chi-tra".

      PAPERLESS_OCR_LANGUAGES=tur ces chi-tra

  Make sure it's a space-separated list when using several values.

  To actually use these languages, also set the default OCR language of paperless:

      PAPERLESS_OCR_LANGUAGE=tur

  Defaults to none, which does not install any additional languages.

  Warning

  This option must not be used in rootless containers.

#### `PAPERLESS_ENABLE_FLOWER=<defined>`

  If this environment variable is defined, the Celery monitoring tool Flower will be started by the container.

  You can read more about this in the advanced documentation.

#### `PAPERLESS_SUPERVISORD_WORKING_DIR=<defined>`

Warning

    This option is deprecated and has no effect.  For read only file system support,
    see [S6_READ_ONLY_ROOT](https://github.com/just-containers/s6-overlay#customizing-s6-overlay-behaviour)
    from s6-overlay.

## Frontend Settings

#### `PAPERLESS_APP_TITLE=<str>`

  If set, overrides the default name "Paperless-ngx"

#### `PAPERLESS_APP_LOGO=<path>`

  Path to an image file in the /media/logo directory, must include 'logo', e.g. `/logo/Atari_logo.svg`

Note

The logo file will be viewable by anyone with access to the Paperless instance login page, so consider your choice of logo carefully and removing exif data from images before uploading.

#### `PAPERLESS_ENABLE_UPDATE_CHECK=<bool>`

Note

This setting was deprecated in favor of a frontend setting after v1.9.2. A one-time migration is performed for users who have this setting set. This setting is always ignored if the corresponding frontend setting has been set.

## Email sending

Setting an SMTP server for the backend will allow you to use the Email workflow action, send documents from the UI as well as reset your password. All of these options come from their similarly-named Django settings

#### `PAPERLESS_EMAIL_HOST=<str>`

  Defaults to 'localhost'.

#### `PAPERLESS_EMAIL_PORT=<int>`

  Defaults to port 25.

#### `PAPERLESS_EMAIL_HOST_USER=<str>`

  Defaults to ''.

#### `PAPERLESS_EMAIL_FROM=<str>`

  Defaults to PAPERLESS_EMAIL_HOST_USER if not set.

#### `PAPERLESS_EMAIL_HOST_PASSWORD=<str>`

  Defaults to ''.

#### `PAPERLESS_EMAIL_USE_TLS=<bool>`

  Defaults to false.

#### `PAPERLESS_EMAIL_USE_SSL=<bool>`

  Defaults to false.

## Remote OCR

#### `PAPERLESS_REMOTE_OCR_ENGINE=<str>`

  The remote OCR engine to use. Currently only Azure AI is supported as "azureai".

  Defaults to None, which disables remote OCR.

#### `PAPERLESS_REMOTE_OCR_API_KEY=<str>`

  The API key to use for the remote OCR engine.

  Defaults to None.

#### `PAPERLESS_REMOTE_OCR_ENDPOINT=<str>`

  The endpoint to use for the remote OCR engine. This is required for Azure AI.

  Defaults to None.

## AI

#### `PAPERLESS_AI_ENABLED=<bool>`

  Enables the AI features in Paperless. This includes the AI-based suggestions. This setting is required to be set to true in order to use the AI features.

  Defaults to false.

#### `PAPERLESS_AI_LLM_EMBEDDING_BACKEND=<str>`

  The embedding backend to use for RAG. This can be "openai-like", "huggingface", or "ollama". The "openai-like" backend uses an OpenAI-compatible embeddings API.

  Defaults to None.

#### `PAPERLESS_AI_LLM_EMBEDDING_MODEL=<str>`

  The model to use for the embedding backend for RAG. This can be set to any of the embedding models supported by the current embedding backend. If not supplied, defaults to "text-embedding-3-small" for the OpenAI-compatible backend, "sentence-transformers/all-MiniLM-L6-v2" for Huggingface, and "embeddinggemma" for Ollama.

  Defaults to None.

#### `PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT=<str>`

  The endpoint / url to use for the embedding backend. If not supplied, embeddings use `PAPERLESS_AI_LLM_ENDPOINT`.

  Defaults to None.

#### `PAPERLESS_AI_LLM_EMBEDDING_CHUNK_SIZE=<int>`

  The chunk size to use when splitting document text for RAG embeddings. Lower this value if your embedding backend or model rejects larger inputs, or silently truncates inputs in a way that harms retrieval quality.

  Defaults to 1024.

#### `PAPERLESS_AI_LLM_CONTEXT_SIZE=<int>`

  The context size to use for AI prompts and RAG retrieval. For Ollama backends, this is also sent as `num_ctx` so models with very large native context windows are not loaded at their maximum context by default.

  Defaults to 8192.

#### `PAPERLESS_AI_LLM_REQUEST_TIMEOUT=<int>`

  The timeout, in seconds, for requests to the configured AI backend. Increase this when using local or slow inference servers that need more time to generate responses.

  Defaults to 120.

#### `PAPERLESS_AI_LLM_BACKEND=<str>`

  The AI backend to use. This can be either "openai-like" or "ollama". If set to "ollama", the AI features will be run locally on your machine. If set to "openai-like", the AI features will use an OpenAI-compatible API endpoint, including OpenAI itself and compatible providers. This setting is required to be set to use the AI features.

  Defaults to None.

  Note

  Remote AI providers may be paid services. If you use a hosted OpenAI-compatible API, you are responsible for any usage charges incurred by Paperless-ngx features, and your document data will be sent to the provider you configure.

  Paperless-ngx does not endorse any specific provider. Refer to your provider's terms of service and privacy policy, and use at your own risk.

#### `PAPERLESS_AI_LLM_MODEL=<str>`

  The model to use for the AI backend, i.e. "gpt-3.5-turbo", "gpt-4" or any of the models supported by the current backend. If not supplied, defaults to "gpt-3.5-turbo" for the OpenAI-compatible backend and "llama3.1" for Ollama.

  Defaults to None.

#### `PAPERLESS_AI_LLM_API_KEY=<str>`

  The API key to use for the AI backend. This is typically required for the OpenAI-compatible backend (optional for others).

  Defaults to None.

#### `PAPERLESS_AI_LLM_ENDPOINT=<str>`

  The endpoint / url to use for the AI backend. This is required for the Ollama backend and may be used with the OpenAI-compatible backend to target a custom provider or local gateway.

  Defaults to None.

#### `PAPERLESS_AI_LLM_OUTPUT_LANGUAGE=<str>`

  The language to use for AI suggestions (results may vary by LLM model). If not supplied, defaults to the user's UI language setting or None.

  Defaults to None.

#### `PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS=<bool>`

  If set to false, Paperless blocks AI endpoint URLs that resolve to non-public addresses (e.g., localhost, etc).

  Defaults to true, which allows internal endpoints.

#### `PAPERLESS_LLM_INDEX_TASK_CRON=<cron expression>`

  Configures the schedule to update the AI embeddings of text content and metadata for all documents. Only performed if AI is enabled and the LLM embedding backend is set.

  Defaults to `10 2 * * *`, once per day.