---
title: InfluxDB 3 Core configuration options
description: InfluxDB 3 Core lets you customize your server configuration by using influxdb3 serve command options or by setting environment variables.
url: https://docs.influxdata.com/influxdb3/core/reference/config-options/
estimated_tokens: 20894
product: InfluxDB 3 Core
version: core
---

# InfluxDB 3 Core configuration options

InfluxDB 3 Core lets you customize your configuration by using `influxdb3` command options or by setting environment variables.

## Configure your server

Pass configuration options using either command options or environment variables. Command options take precedence over environment variables.

### TOML configuration files

DEB and RPM installs include a TOML configuration file at `/etc/influxdb3/influxdb3-core.conf`. The systemd launcher reads this file and converts each entry to an `INFLUXDB3_*` environment variable (the pattern is `INFLUXDB3_<KEY>` with hyphens replaced by underscores and uppercased) before invoking `influxdb3 serve`.

`influxdb3 serve` does not yet natively read TOML; the file’s effect is applied through the environment variables the launcher sets. CLI flags passed to `influxdb3 serve` still override values defined in the TOML file because they override the environment variables that file becomes.

For day-to-day systemd operation — including the edit-and-restart workflow for applying changes — see [Run as a system service (Linux)](/influxdb3/core/install/#run-as-a-system-service-linux).

### Global vs serve-specific options

Some options are **global** (specified before the command) while others are **serve-specific** (specified after `serve`):

-   **Global options**: Apply to the `influxdb3` CLI itself (for example, `--num-io-threads`)
-   **Serve options**: Apply only to the `serve` command (for example, `--node-id`, `--object-store`, `--verbose`)

#### Example command with global and serve-specific options

```sh
influxdb3 --num-io-threads=4 serve \
  --node-id node0 \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --verbose \
  --log-filter info
```

##### Example environment variables

```sh

export INFLUXDB3_NODE_IDENTIFIER_PREFIX=my-node
export INFLUXDB3_OBJECT_STORE=file
export INFLUXDB3_DB_DIR=~/.influxdb3
export INFLUXDB3_LOG_FILTER=info

influxdb3 serve
```

## Global configuration options

The following options apply to the `influxdb3` CLI globally and must be specified **before** any subcommand (for example, `serve`):

### num-io-threads

Sets the number of threads allocated to the IO runtime thread pool. IO threads handle HTTP request serving, line protocol parsing, and file operations.

`--num-io-threads` is a **global option** that must be specified before the `serve` command.

```bash
# Set IO threads (global option before serve)
influxdb3 --num-io-threads=8 serve --node-id=node0 --object-store=file
```

| influxdb3 option | Environment variable |
| --- | --- |
| --num-io-threads | INFLUXDB3_NUM_IO_THREADS |

## Server configuration options

-   [General](#general)
    
-   [Security](#security)
    
-   [AWS](#aws)
    
-   [Google Cloud Service](#google-cloud-service)
    
-   [Microsoft Azure](#microsoft-azure)
    
-   [Object Storage](#object-storage)
    
-   [Logs](#logs)
    
-   [Traces](#traces)
    
-   [DataFusion](#datafusion)
    
-   [HTTP](#http)
    
-   [Memory](#memory)
    
-   [Write-Ahead Log (WAL)](#write-ahead-log-wal)
    
-   [Compaction](#compaction)
    
-   [Caching](#caching)
    
-   [Processing Engine](#processing-engine)
    
-   [Resource Limits](#resource-limits)
    
-   [Data Lifecycle Management](#data-lifecycle-management)
    
-   [Telemetry](#telemetry)
    
-   [TCP Listeners](#tcp-listeners)
    

### General

-   [data-dir](#data-dir)
    
-   [node-id](#node-id)
    
-   [object-store](#object-store)
    
-   [query-file-limit](#query-file-limit)
    

#### data-dir

For the `file` object store, defines the location InfluxDB 3 Core uses to store files locally. Required when using the `file` [object store](#object-store).

| influxdb3 serve option | Environment variable |
| --- | --- |
| --data-dir | INFLUXDB3_DB_DIR |

#### node-id

Specifies the node identifier used as a prefix in all object store file paths. This should be unique for any hosts sharing the same object store configuration–for example, the same bucket.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --node-id | INFLUXDB3_NODE_IDENTIFIER_PREFIX |

#### object-store

Specifies which object storage to use to store Parquet files. This option supports the following values:

-   `memory`: Effectively no object persistence
-   `memory-throttled`: Like `memory` but with latency and throughput that somewhat resembles a cloud object store
-   `file`: Stores objects in the local filesystem (must also set `--data-dir`)
-   `s3`: Amazon S3 (must also set `--bucket`, `--aws-access-key-id`, `--aws-secret-access-key`, and possibly `--aws-default-region`)
-   `google`: Google Cloud Storage (must also set `--bucket` and `--google-service-account`)
-   `azure`: Microsoft Azure blob storage (must also set `--bucket`, `--azure-storage-account`, and `--azure-storage-access-key`)

| influxdb3 serve option | Environment variable |
| --- | --- |
| --object-store | INFLUXDB3_OBJECT_STORE |

### Security

-   [tls-key](#tls-key)
-   [tls-cert](#tls-cert)
-   [tls-minimum-versions](#tls-minimum-version)
-   [without-auth](#without-auth)
-   [disable-authz](#disable-authz)
-   [admin-token-recovery-http-bind](#admin-token-recovery-http-bind)
-   [admin-token-file](#admin-token-file)

#### tls-key

The path to a key file for TLS to be enabled.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --tls-key | INFLUXDB3_TLS_KEY |

#### tls-cert

The path to a cert file for TLS to be enabled.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --tls-cert | INFLUXDB3_TLS_CERT |

#### tls-minimum-version

The minimum version for TLS. Valid values are `tls-1.2` or `tls-1.3`. Default is `tls-1.2`.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --tls-minimum-version | INFLUXDB3_TLS_MINIMUM_VERSION |

#### without-auth

Disables authentication for all server actions (CLI commands and API requests). The server processes all requests without requiring tokens or authentication.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --without-auth | INFLUXDB3_START_WITHOUT_AUTH |

#### disable-authz

Optionally disable authz by passing in a comma separated list of resources. Valid values are `health`, `ping`, and `metrics`.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --disable-authz | INFLUXDB3_DISABLE_AUTHZ |

#### admin-token-recovery-http-bind

Enables an admin token recovery HTTP server on a separate port. This server allows regenerating lost admin tokens without existing authentication. The server automatically shuts down after a successful token regeneration.

This option creates an unauthenticated endpoint that can regenerate admin tokens. Only use this when you have lost access to your admin token and ensure the server is only accessible from trusted networks.

**Default:** `127.0.0.1:8182` (when enabled)

| influxdb3 serve option | Environment variable |
| --- | --- |
| --admin-token-recovery-http-bind | INFLUXDB3_ADMIN_TOKEN_RECOVERY_HTTP_BIND |

##### Example usage

```bash
# Start server with recovery endpoint
influxdb3 serve --admin-token-recovery-http-bind

# In another terminal, regenerate the admin token
influxdb3 create token --admin --regenerate --host http://127.0.0.1:8182
```

#### admin-token-file

Specifies an offline admin token file to use if no tokens exist when the server starts. Once started, you can interact with the server using the provided token. Offline admin tokens are designed to help with automated deployments.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --admin-token-file | INFLUXDB3_ADMIN_TOKEN_FILE |

Offline admin tokens are defined in a JSON-formatted file. Use the following command to generate an offline admin token file:

```bash
influxdb3 create token --admin \
  --name "example-admin-token" \
  --expiry 1d \
  --offline \
  --output-file ./path/to/admin-token.json
```

[](#view-example-offline-admin-token-file)

View example offline admin token file

```json
{
  "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
  "name": "example-admin-token",
  "expiry_millis": 1756400061529
}
```

##### Example usage

```bash
# Generate an admin token offline
influxdb3 create token \
  --admin \
  --name "example-admin-token" \
  --expiry 1d \
  --offline \
  --output-file ./path/to/admin-token.json

# Start InfluxDB 3 Core using the generated token
influxdb3 serve --admin-token-file ./path/to/admin-token.json
```

### AWS

-   [aws-access-key-id](#aws-access-key-id)
-   [aws-secret-access-key](#aws-secret-access-key)
-   [aws-default-region](#aws-default-region)
-   [aws-endpoint](#aws-endpoint)
-   [aws-session-token](#aws-session-token)
-   [aws-allow-http](#aws-allow-http)
-   [aws-skip-signature](#aws-skip-signature)
-   [aws-credentials-file](#aws-credentials-file)

#### aws-access-key-id

When using Amazon S3 as the object store, set this to an access key that has permission to read from and write to the specified S3 bucket.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-access-key-id | AWS_ACCESS_KEY_ID |

#### aws-secret-access-key

When using Amazon S3 as the object store, set this to the secret access key that goes with the specified access key ID.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-secret-access-key | AWS_SECRET_ACCESS_KEY |

#### aws-default-region

When using Amazon S3 as the object store, set this to the region that goes with the specified bucket if different from the fallback value.

**Default:** `us-east-1`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-default-region | AWS_DEFAULT_REGION |

#### aws-endpoint

When using an Amazon S3 compatibility storage service, set this to the endpoint.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-endpoint | AWS_ENDPOINT |

#### aws-session-token

When using Amazon S3 as an object store, set this to the session token. This is handy when using a federated login or SSO and fetching credentials via the UI.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-session-token | AWS_SESSION_TOKEN |

#### aws-allow-http

Allows unencrypted HTTP connections to AWS.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-allow-http | AWS_ALLOW_HTTP |

#### aws-skip-signature

If enabled, S3 object stores do not fetch credentials and do not sign requests.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-skip-signature | AWS_SKIP_SIGNATURE |

#### aws-credentials-file

Specifies the path to your S3 credentials file. When using a credentials file, settings in the file override the corresponding CLI flags.

S3 credential files are JSON-formatted and should contain the following:

```json
{
  "aws_access_key_id": "AWS_ACCESS_KEY_ID",
  "aws_secret_access_key": "AWS_SECRET_ACCESS_KEY",
  "aws_session_token": "AWS_SESSION_TOKEN",
  "expiry": "UNIX_SECONDS_TIMESTAMP"
}
```

The `aws_session_token` and `expiry` fields are optional. The file is automatically checked for updates at the expiry time or at 1-hour intervals.

If the object store returns an “Unauthenticated” error, InfluxDB will attempt to update its in-memory credentials from this file and then retry the object store request.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --aws-credentials-file | AWS_CREDENTIALS_FILE |

### Google Cloud Service

-   [google-service-account](#google-service-account)

#### google-service-account

When using Google Cloud Storage as the object store, set this to the path to the JSON file that contains the Google credentials.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --google-service-account | GOOGLE_SERVICE_ACCOUNT |

### Microsoft Azure

-   [azure-storage-account](#azure-storage-account)
-   [azure-storage-access-key](#azure-storage-access-key)
-   [azure-endpoint](#azure-endpoint)
-   [azure-allow-http](#azure-allow-http)

#### azure-storage-account

When using Microsoft Azure as the object store, set this to the name you see when navigating to **All Services > Storage accounts > `[name]`**.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --azure-storage-account | AZURE_STORAGE_ACCOUNT |

#### azure-storage-access-key

When using Microsoft Azure as the object store, set this to one of the Key values in the Storage account’s **Settings > Access keys**.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --azure-storage-access-key | AZURE_STORAGE_ACCESS_KEY |

#### azure-endpoint

When using Microsoft Azure as the object store, set this to the Azure Blob Storage endpoint.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --azure-endpoint | AZURE_ENDPOINT |

#### azure-allow-http

When using Microsoft Azure as the object store, allow unencrypted HTTP requests to Azure Blob Storage.

**Default:** `false`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --azure-allow-http | AZURE_ALLOW_HTTP |

### Object Storage

-   [bucket](#bucket)
-   [object-store-connection-limit](#object-store-connection-limit)
-   [object-store-http2-only](#object-store-http2-only)
-   [object-store-http2-max-frame-size](#object-store-http2-max-frame-size)
-   [object-store-request-timeout](#object-store-request-timeout)
-   [object-store-max-retries](#object-store-max-retries)
-   [object-store-retry-timeout](#object-store-retry-timeout)
-   [object-store-cache-endpoint](#object-store-cache-endpoint)
-   [object-store-tls-allow-insecure](#object-store-tls-allow-insecure)
-   [object-store-tls-ca](#object-store-tls-ca)

#### bucket

Sets the name of the object storage bucket to use. Must also set `--object-store` to a cloud object storage for this option to take effect.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --bucket | INFLUXDB3_BUCKET |

#### object-store-connection-limit

When using a network-based object store, limits the number of connections to this value.

**Default:** `16`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-connection-limit | INFLUXDB3_OBJECT_STORE_CONNECTION_LIMIT (preferred)OBJECT_STORE_CONNECTION_LIMIT (deprecated; supported for backward compatibility) |

#### object-store-http2-only

Forces HTTP/2 connections to network-based object stores.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-http2-only | INFLUXDB3_OBJECT_STORE_HTTP2_ONLY (preferred)OBJECT_STORE_HTTP2_ONLY (deprecated; supported for backward compatibility) |

#### object-store-http2-max-frame-size

Sets the maximum frame size (in bytes/octets) for HTTP/2 connections.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-http2-max-frame-size | INFLUXDB3_OBJECT_STORE_HTTP2_MAX_FRAME_SIZE (preferred)OBJECT_STORE_HTTP2_MAX_FRAME_SIZE (deprecated; supported for backward compatibility) |

#### object-store-request-timeout

Sets the HTTP request timeout for object store requests.

**Default:** `30s`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-request-timeout | INFLUXDB3_OBJECT_STORE_REQUEST_TIMEOUT (preferred)OBJECT_STORE_REQUEST_TIMEOUT (deprecated; supported for backward compatibility) |

#### object-store-max-retries

Defines the maximum number of times to retry a request.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-max-retries | INFLUXDB3_OBJECT_STORE_MAX_RETRIES (preferred)OBJECT_STORE_MAX_RETRIES (deprecated; supported for backward compatibility) |

#### object-store-retry-timeout

Specifies the maximum length of time from the initial request after which no further retries are be attempted.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-retry-timeout | INFLUXDB3_OBJECT_STORE_RETRY_TIMEOUT (preferred)OBJECT_STORE_RETRY_TIMEOUT (deprecated; supported for backward compatibility) |

#### object-store-cache-endpoint

Sets the endpoint of an S3-compatible, HTTP/2-enabled object store cache.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-cache-endpoint | INFLUXDB3_OBJECT_STORE_CACHE_ENDPOINT (preferred)OBJECT_STORE_CACHE_ENDPOINT (deprecated; supported for backward compatibility) |

#### object-store-tls-allow-insecure

Allows invalid TLS certificates when connecting to object storage.

This disables TLS certificate verification and should only be used for testing.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-tls-allow-insecure | INFLUXDB3_OBJECT_STORE_TLS_ALLOW_INSECURE (preferred)OBJECT_STORE_TLS_ALLOW_INSECURE (deprecated; supported for backward compatibility) |

#### object-store-tls-ca

Specifies the path to a custom CA certificate file (PEM format) for verifying object store connections. Use this when your object store uses a certificate signed by a private CA.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --object-store-tls-ca | INFLUXDB3_OBJECT_STORE_TLS_CA (preferred)OBJECT_STORE_TLS_CA (deprecated; supported for backward compatibility) |

### Logs

-   [log-filter](#log-filter)
-   [log-destination](#log-destination)
-   [log-format](#log-format)
-   [query-log-size](#query-log-size)

#### log-filter

Sets the filter directive for logs. Use this option to control the verbosity of server logs globally or for specific components.

##### Log levels

The following log levels are available (from least to most verbose):

| Level | Description |
| --- | --- |
| error | Only errors |
| warn | Warnings and errors |
| info | Informational messages, warnings, and errors (default) |
| debug | Debug information for troubleshooting, plus all above levels |
| trace | Very detailed tracing information, plus all above levels (produces high log volume) |

##### Basic usage

To set the log level globally, pass one of the log levels:

```sh
influxdb3 serve --log-filter debug
```

##### Targeted filtering

Globally enabling `debug` or `trace` produces a high volume of log output. For more targeted debugging, you can set different log levels for specific components using the format `<global_level>,<component>=<level>`.

###### Debug write buffer operations

```sh
influxdb3 serve --log-filter info,influxdb3_write_buffer=debug
```

###### Trace WAL operations

```sh
influxdb3 serve --log-filter info,influxdb3_wal=trace
```

###### Multiple targeted filters

```sh
influxdb3 serve --log-filter info,influxdb3_write_buffer=debug,influxdb3_wal=debug
```

##### Common component names

The following are common component names you can use for targeted filtering:

| Component | Description |
| --- | --- |
| influxdb3_write_buffer | Write buffer operations |
| influxdb3_wal | Write-ahead log operations |
| influxdb3_catalog | Catalog and schema operations |
| influxdb3_cache | Caching operations |

Targeted filtering requires knowledge of the codebase component names. The component names correspond to Rust package names in the InfluxDB 3 source code. Use `debug` or `trace` sparingly on specific components to avoid excessive log output.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --log-filter | INFLUXDB3_LOG_FILTER (preferred)LOG_FILTER (deprecated; supported for backward compatibility) |

#### log-destination

Specifies the destination for logs.

This option supports the following values:

-   `stdout` *(default)*
-   `stderr`

**Default:** `stdout`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --log-destination | INFLUXDB3_LOG_DESTINATION (preferred)LOG_DESTINATION (deprecated; supported for backward compatibility) |

#### log-format

Defines the message format for logs.

This option supports the following values:

-   `full` *(default)*

**Default:** `full`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --log-format | INFLUXDB3_LOG_FORMAT (preferred)LOG_FORMAT (deprecated; supported for backward compatibility) |

#### query-log-size

Defines the size of the query log. Up to this many queries remain in the log before older queries are evicted to make room for new ones.

**Default:** `1000`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --query-log-size | INFLUXDB3_QUERY_LOG_SIZE |

### Traces

-   [traces-exporter](#traces-exporter)
-   [traces-exporter-jaeger-agent-host](#traces-exporter-jaeger-agent-host)
-   [traces-exporter-jaeger-agent-port](#traces-exporter-jaeger-agent-port)
-   [traces-exporter-jaeger-service-name](#traces-exporter-jaeger-service-name)
-   [traces-exporter-jaeger-trace-context-header-name](#traces-exporter-jaeger-trace-context-header-name)
-   [traces-jaeger-debug-name](#traces-jaeger-debug-name)
-   [traces-jaeger-tags](#traces-jaeger-tags)
-   [traces-jaeger-max-msgs-per-second](#traces-jaeger-max-msgs-per-second)

#### traces-exporter

Sets the type of tracing exporter.

**Default:** `none`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-exporter | INFLUXDB3_TRACES_EXPORTER (preferred)TRACES_EXPORTER (deprecated; supported for backward compatibility) |

#### traces-exporter-jaeger-agent-host

Specifies the Jaeger agent network hostname for tracing.

**Default:** `0.0.0.0`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-exporter-jaeger-agent-host | INFLUXDB3_TRACES_EXPORTER_JAEGER_AGENT_HOST (preferred)TRACES_EXPORTER_JAEGER_AGENT_HOST (deprecated; supported for backward compatibility) |

#### traces-exporter-jaeger-agent-port

Defines the Jaeger agent network port for tracing.

**Default:** `6831`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-exporter-jaeger-agent-port | INFLUXDB3_TRACES_EXPORTER_JAEGER_AGENT_PORT (preferred)TRACES_EXPORTER_JAEGER_AGENT_PORT (deprecated; supported for backward compatibility) |

#### traces-exporter-jaeger-service-name

Sets the Jaeger service name for tracing.

**Default:** `iox-conductor`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-exporter-jaeger-service-name | INFLUXDB3_TRACES_EXPORTER_JAEGER_SERVICE_NAME (preferred)TRACES_EXPORTER_JAEGER_SERVICE_NAME (deprecated; supported for backward compatibility) |

#### traces-exporter-jaeger-trace-context-header-name

Specifies the header name used for passing trace context.

**Default:** `uber-trace-id`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-exporter-jaeger-trace-context-header-name | INFLUXDB3_TRACES_EXPORTER_JAEGER_TRACE_CONTEXT_HEADER_NAME (preferred)TRACES_EXPORTER_JAEGER_TRACE_CONTEXT_HEADER_NAME (deprecated; supported for backward compatibility) |

#### traces-jaeger-debug-name

Specifies the header name used for force sampling in tracing.

**Default:** `jaeger-debug-id`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-jaeger-debug-name | INFLUXDB3_TRACES_EXPORTER_JAEGER_DEBUG_NAME (preferred)TRACES_EXPORTER_JAEGER_DEBUG_NAME (deprecated; supported for backward compatibility) |

#### traces-jaeger-tags

Defines a set of `key=value` pairs to annotate tracing spans with.

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-jaeger-tags | INFLUXDB3_TRACES_EXPORTER_JAEGER_TAGS (preferred)TRACES_EXPORTER_JAEGER_TAGS (deprecated; supported for backward compatibility) |

#### traces-jaeger-max-msgs-per-second

Specifies the maximum number of messages sent to a Jaeger service per second.

**Default:** `1000`

| influxdb3 serve option | Environment variables |
| --- | --- |
| --traces-jaeger-max-msgs-per-second | INFLUXDB3_TRACES_JAEGER_MAX_MSGS_PER_SECOND (preferred)TRACES_JAEGER_MAX_MSGS_PER_SECOND (deprecated; supported for backward compatibility) |

### DataFusion

-   [datafusion-num-threads](#datafusion-num-threads)
-   [datafusion-max-parquet-fanout](#datafusion-max-parquet-fanout)
-   [datafusion-use-cached-parquet-loader](#datafusion-use-cached-parquet-loader)
-   [datafusion-config](#datafusion-config)

#### datafusion-num-threads

Sets the maximum number of DataFusion runtime threads to use.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --datafusion-num-threads | INFLUXDB3_DATAFUSION_NUM_THREADS |

#### datafusion-max-parquet-fanout

When multiple Parquet files are required in a sorted way (deduplication for example), specifies the maximum fanout.

**Default:** `1000`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --datafusion-max-parquet-fanout | INFLUXDB3_DATAFUSION_MAX_PARQUET_FANOUT |

#### datafusion-use-cached-parquet-loader

Uses a cached Parquet loader when reading Parquet files from the object store.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --datafusion-use-cached-parquet-loader | INFLUXDB3_DATAFUSION_USE_CACHED_PARQUET_LOADER |

#### datafusion-config

Provides custom configuration to DataFusion as a comma-separated list of `key:value` pairs.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --datafusion-config | INFLUXDB3_DATAFUSION_CONFIG |

### HTTP

-   [max-http-request-size](#max-http-request-size)
-   [http-bind](#http-bind)

#### max-http-request-size

Specifies the maximum size of HTTP requests.

**Default:** `10485760`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --max-http-request-size | INFLUXDB3_MAX_HTTP_REQUEST_SIZE |

#### http-bind

Defines the address on which InfluxDB serves HTTP API requests.

**Default:** `0.0.0.0:8181`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --http-bind | INFLUXDB3_HTTP_BIND_ADDR |

### Memory

-   [exec-mem-pool-bytes](#exec-mem-pool-bytes)
-   [force-snapshot-mem-threshold](#force-snapshot-mem-threshold)

#### exec-mem-pool-bytes

Specifies the size of the memory pool used for query processing and data operations. This memory pool is used when InfluxDB 3 Core processes queries and performs internal data management tasks. Can be given as absolute value in bytes or as a percentage of the total available memory–for example: `8000000000` or `10%`.

**Default:** `8589934592`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --exec-mem-pool-bytes | INFLUXDB3_EXEC_MEM_POOL_BYTES |

#### force-snapshot-mem-threshold

Specifies the threshold for the internal memory buffer. Supports either a percentage (portion of available memory) or absolute value in MB–for example: `70%` or `1000`.

**Default:** `70%`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --force-snapshot-mem-threshold | INFLUXDB3_FORCE_SNAPSHOT_MEM_THRESHOLD |

### Write-Ahead Log (WAL)

-   [checkpoint-interval](#checkpoint-interval)
-   [wal-flush-interval](#wal-flush-interval)
-   [wal-snapshot-size](#wal-snapshot-size)
-   [wal-max-write-buffer-size](#wal-max-write-buffer-size)
-   [snapshotted-wal-files-to-keep](#snapshotted-wal-files-to-keep)
-   [wal-replay-fail-on-error](#wal-replay-fail-on-error)
-   [wal-replay-concurrency-limit](#wal-replay-concurrency-limit)

#### checkpoint-interval

Sets the interval for consolidating [snapshots](/influxdb3/core/admin/backup-restore/#file-structure) into monthly checkpoints for faster server startup. Snapshots accumulate in object storage over time and are not automatically deleted.

Without checkpointing, the server loads individual snapshots on startup. The number of snapshots is determined by the lookback window ([`gen1-lookback-duration`](#gen1-lookback-duration), default 1 month) divided by [`gen1-duration`](#gen1-duration) (default 10 minutes), with a minimum of 100. With default settings, that can be up to ~4,320 snapshots.

With checkpointing enabled, the server periodically consolidates snapshot metadata into checkpoints in object storage. On startup, the server loads one to two checkpoints per calendar month, then loads only snapshots created since the last checkpoint. Enabling checkpointing does not delete old snapshots.

Up to 10 checkpoints load concurrently during startup. The server retains two checkpoints per calendar month and handles month rollovers automatically.

Accepts a [duration](/influxdb3/core/reference/glossary/#duration) value–for example: `1h`, `30m`, `10m`.

**Default:** *Not set (disabled)*

| influxdb3 serve option | Environment variable |
| --- | --- |
| --checkpoint-interval | INFLUXDB3_CHECKPOINT_INTERVAL |

##### Example

```bash
influxdb3 serve --checkpoint-interval 1h
```

#### wal-flush-interval

Specifies the interval to flush buffered data to a WAL file. Writes that wait for WAL confirmation take up to this interval to complete. Use `s` for seconds or `ms` for milliseconds. For local disks, `100 ms` is recommended.

**Default:** `1s`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --wal-flush-interval | INFLUXDB3_WAL_FLUSH_INTERVAL |

#### wal-snapshot-size

Defines the number of WAL files to attempt to remove in a snapshot. This, multiplied by the interval, determines how often snapshots are taken.

**Default:** `600`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --wal-snapshot-size | INFLUXDB3_WAL_SNAPSHOT_SIZE |

#### wal-max-write-buffer-size

Specifies the maximum number of write requests that can be buffered before a flush must be executed and succeed.

**Default:** `100000`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --wal-max-write-buffer-size | INFLUXDB3_WAL_MAX_WRITE_BUFFER_SIZE |

#### snapshotted-wal-files-to-keep

Specifies the number of snapshotted WAL files to retain in the object store. Flushing the WAL files does not clear the WAL files immediately; they are deleted when the number of snapshotted WAL files exceeds this number.

**Default:** `300`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --snapshotted-wal-files-to-keep | INFLUXDB3_NUM_WAL_FILES_TO_KEEP |

#### wal-replay-fail-on-error

Determines whether WAL replay should fail when encountering errors.

**Default:** `false`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --wal-replay-fail-on-error | INFLUXDB3_WAL_REPLAY_FAIL_ON_ERROR |

#### wal-replay-concurrency-limit

Concurrency limit during WAL replay. Setting this number too high can lead to OOM. The default is dynamically determined.

**Default:** `max(num_cpus, 10)`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --wal-replay-concurrency-limit | INFLUXDB3_WAL_REPLAY_CONCURRENCY_LIMIT |

### Compaction

-   [gen1-duration](#gen1-duration)

#### gen1-duration

Specifies the duration that Parquet files are arranged into. Data timestamps land each row into a file of this duration. Supported durations are `1m`, `5m`, and `10m`. These files are known as “generation 1” files that the compactor in InfluxDB 3 Enterprise can merge into larger generations .

**Default:** `10m`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --gen1-duration | INFLUXDB3_GEN1_DURATION |

### Caching

-   [preemptive-cache-age](#preemptive-cache-age)
    
-   [parquet-mem-cache-size](#parquet-mem-cache-size)
    
-   [parquet-mem-cache-prune-percentage](#parquet-mem-cache-prune-percentage)
    
-   [parquet-mem-cache-prune-interval](#parquet-mem-cache-prune-interval)
    
-   [parquet-mem-cache-query-path-duration](#parquet-mem-cache-query-path-duration)
    
-   [disable-parquet-mem-cache](#disable-parquet-mem-cache)
    
-   [table-index-cache-max-entries](#table-index-cache-max-entries)
    
-   [table-index-cache-concurrency-limit](#table-index-cache-concurrency-limit)
    
-   [last-cache-eviction-interval](#last-cache-eviction-interval)
    
-   [distinct-cache-eviction-interval](#distinct-cache-eviction-interval)
    

#### preemptive-cache-age

Specifies the interval to prefetch into the Parquet cache during compaction.

**Default:** `3d`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --preemptive-cache-age | INFLUXDB3_PREEMPTIVE_CACHE_AGE |

#### parquet-mem-cache-size

Specifies the size of the in-memory Parquet cache. Accepts values in megabytes (as an integer) or as a percentage of total available memory (for example, `20%`, `4096`).

**Default:** `20%`

#### Breaking change in v3.0.0

In v3.0.0, `--parquet-mem-cache-size-mb` was replaced with `--parquet-mem-cache-size`. The new option accepts both megabytes (integer) and percentage values. The default changed from `1000` MB to `20%` of total available memory.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --parquet-mem-cache-size | INFLUXDB3_PARQUET_MEM_CACHE_SIZE |

#### parquet-mem-cache-prune-percentage

Specifies the percentage of entries to prune during a prune operation on the in-memory Parquet cache.

**Default:** `0.1`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --parquet-mem-cache-prune-percentage | INFLUXDB3_PARQUET_MEM_CACHE_PRUNE_PERCENTAGE |

#### parquet-mem-cache-prune-interval

Sets the interval to check if the in-memory Parquet cache needs to be pruned.

**Default:** `1s`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --parquet-mem-cache-prune-interval | INFLUXDB3_PARQUET_MEM_CACHE_PRUNE_INTERVAL |

#### parquet-mem-cache-query-path-duration

Specifies

the time window for caching recent Parquet files in memory. Default is `5h`.

Only files containing data with a timestamp between `now` and `now - duration` are cached when accessed during queries–for example, with the default `5h` setting:

-   Current time: `2024-06-10 15:00:00`
-   Cache window: Last 5 hours (`2024-06-10 10:00:00` to now)

If a query requests data from `2024-06-09` (old) and `2024-06-10 14:00` (recent):

-   **Cached**: Parquet files with data from `2024-06-10 14:00` (within 5-hour window)
-   **Not cached**: Parquet files with data from `2024-06-09` (outside 5-hour window)

| influxdb3 serve option | Environment variable |
| --- | --- |
| --parquet-mem-cache-query-path-duration | INFLUXDB3_PARQUET_MEM_CACHE_QUERY_PATH_DURATION |

#### disable-parquet-mem-cache

Disables the in-memory Parquet cache. By default, the cache is enabled.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --disable-parquet-mem-cache | INFLUXDB3_DISABLE_PARQUET_MEM_CACHE |

#### table-index-cache-max-entries

Specifies the maximum number of entries in the table index cache.

**Default:** `1000`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --table-index-cache-max-entries | INFLUXDB3_TABLE_INDEX_CACHE_MAX_ENTRIES |

#### table-index-cache-concurrency-limit

Limits the concurrency level for table index cache operations.

**Default:** `8`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --table-index-cache-concurrency-limit | INFLUXDB3_TABLE_INDEX_CACHE_CONCURRENCY_LIMIT |

#### last-cache-eviction-interval

Specifies the interval to evict expired entries from the Last-N-Value cache, expressed as a human-readable duration–for example: `20s`, `1m`, `1h`.

**Default:** `10s`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --last-cache-eviction-interval | INFLUXDB3_LAST_CACHE_EVICTION_INTERVAL |

#### distinct-cache-eviction-interval

Specifies the interval to evict expired entries from the distinct value cache, expressed as a human-readable duration–for example: `20s`, `1m`, `1h`.

**Default:** `10s`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --distinct-cache-eviction-interval | INFLUXDB3_DISTINCT_CACHE_EVICTION_INTERVAL |

#### query-file-limit

Limits the number of Parquet files a query can access. If a query attempts to read more than this limit, InfluxDB 3 Core returns an error.

**Default:** `432`

With the default `432` setting and the default [`gen1-duration`](#gen1-duration) setting of 10 minutes, queries can access up to a 72 hours of data, but potentially less depending on whether all data for a given 10 minute block of time was ingested during the same period.

You can increase this limit to allow more files to be queried, but be aware of the following side-effects:

-   Degraded query performance for queries that read more Parquet files
-   Increased memory usage
-   Your system potentially killing the `influxdb3` process due to Out-of-Memory (OOM) errors
-   If using object storage to store data, many GET requests to access the data (as many as 2 per file)

We recommend keeping the default setting and querying smaller time ranges. If you need to query longer time ranges or faster query performance on any query that accesses an hour or more of data, [InfluxDB 3 Enterprise](/influxdb3/enterprise/) optimizes data storage by compacting and rearranging Parquet files to achieve faster query performance.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --query-file-limit | INFLUXDB3_QUERY_FILE_LIMIT |

### Processing Engine

-   [plugin-dir](#plugin-dir)
-   [plugin-repo](#plugin-repo)
-   [virtual-env-location](#virtual-env-location)
-   [package-manager](#package-manager)

#### plugin-dir

Specifies the local directory that contains Python plugins and their test files.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --plugin-dir | INFLUXDB3_PLUGIN_DIR |

##### Default behavior by deployment type

| Deployment | Default state | Configuration |
| --- | --- | --- |
| Docker images | Enabled | INFLUXDB3_PLUGIN_DIR=/plugins |
| DEB/RPM packages | Enabled | plugin-dir="/var/lib/influxdb3/plugins" |
| Binary/source | Disabled | No plugin-dir configured |

##### Disable the Processing Engine

To disable the Processing Engine, ensure `plugin-dir` is not configured.

Setting `plugin-dir=""` or `INFLUXDB3_PLUGIN_DIR=""` (empty string) does **not** disable the Processing Engine. You must comment out, remove, or unset the configuration — not set it to empty.

**Docker:** Use a custom entrypoint:

```bash
docker run --entrypoint /bin/sh influxdb:3-core -c 'unset INFLUXDB3_PLUGIN_DIR && exec influxdb3 serve --object-store memory'
```

**systemd (DEB/RPM):** Comment out or remove `plugin-dir` in the configuration file:

```bash
sudo nano /etc/influxdb3/influxdb3-core.conf
```

```toml
# plugin-dir="/var/lib/influxdb3/plugins"
```

Then restart the service:

```bash
sudo systemctl restart influxdb3-core
```

When the Processing Engine is disabled:

-   The Python environment and PyO3 bindings are not initialized
-   Plugin-related operations return a “No plugin directory configured” error
-   The server runs with reduced resource usage

#### plugin-repo

Specifies the base URL of the remote repository used when referencing plugins with the `gh:` prefix. When you create a trigger with a plugin filename starting with `gh:`, InfluxDB fetches the plugin code from this repository URL.

The URL construction automatically handles trailing slashes—both formats work identically:

-   `https://example.com/plugins/` (with trailing slash)
-   `https://example.com/plugins` (without trailing slash)

**Default:** The official InfluxDB 3 plugins repository at `https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --plugin-repo | INFLUXDB3_PLUGIN_REPO |

##### Example usage

```bash
# Use a custom organization repository
influxdb3 serve \
  --plugin-dir ~/.plugins \
  --plugin-repo "https://raw.githubusercontent.com/myorg/influxdb-plugins/main/"

# Use an internal mirror
influxdb3 serve \
  --plugin-dir ~/.plugins \
  --plugin-repo "https://internal.company.com/influxdb-plugins/"

# Set via environment variable
export INFLUXDB3_PLUGIN_REPO="https://custom-repo.example.com/plugins/"
influxdb3 serve --plugin-dir ~/.plugins
```

#### virtual-env-location

Specifies the location of the Python virtual environment that the processing engine uses.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --virtual-env-location | VIRTUAL_ENV |

#### package-manager

Specifies the Python package manager that the Processing Engine uses to install plugin dependencies.

This option supports the following values:

-   `discover` *(default)*: Automatically detect and use available package manager (`uv` or `pip`)
-   `pip`: Use pip package manager exclusively
-   `uv`: Use uv package manager exclusively
-   `disabled`: Disable automatic package installation (all dependencies must be pre-installed)

**Default:** `discover`

##### Security mode (disabled)

When set to `disabled`, InfluxDB 3 Core blocks all package installation attempts for security and compliance requirements. The Processing Engine and plugins continue to function normally, but package installation requests (via CLI or API) return a `403 Forbidden` error.

This mode is designed for:

-   **Enterprise security requirements**: Prevent arbitrary package installation
-   **Compliance environments**: Control exactly which packages are available
-   **Air-gapped deployments**: Pre-install all dependencies before deployment
-   **Multi-tenant scenarios**: Prevent tenants from installing potentially malicious packages

Before using `--package-manager disabled`, administrators must pre-install all required Python packages into the virtual environment that plugins will use.

**Example:**

```bash
# Start InfluxDB 3 with disabled package manager
influxdb3 serve \
  --node-id node0 \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --plugin-dir ~/.plugins \
  --package-manager disabled
```

For more information about plugins and package management, see [Processing Engine plugins](/influxdb3/core/plugins/).

| influxdb3 serve option | Environment variable |
| --- | --- |
| --package-manager | INFLUXDB3_PACKAGE_MANAGER |

### Resource Limits

-   [datafusion-num-threads](#datafusion-num-threads)
    
-   *[num-io-threads](#num-io-threads) - See [Global configuration options](#global-configuration-options)*
    
    ```
     |                                  |
    
    ```
    

#### datafusion-num-threads

Sets the number of threads allocated to the DataFusion runtime thread pool. DataFusion threads handle:

-   Query execution and processing
-   Data aggregation and transformation
-   Snapshot creation (sort/dedupe operations)
-   Parquet file generation

**Default:** All available cores minus IO threads

DataFusion threads are used for both query processing and snapshot operations.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --datafusion-num-threads | INFLUXDB3_DATAFUSION_NUM_THREADS |

[`--num-io-threads`](#num-io-threads) is a [global configuration option](#global-configuration-options).

### Data Lifecycle Management

-   [gen1-lookback-duration](#gen1-lookback-duration)
-   [retention-check-interval](#retention-check-interval)
-   [delete-grace-period](#delete-grace-period)
-   [hard-delete-default-duration](#hard-delete-default-duration)

#### gen1-lookback-duration

Specifies how far back to look when creating generation 1 Parquet files.

**Default:** `24h`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --gen1-lookback-duration | INFLUXDB3_GEN1_LOOKBACK_DURATION |

#### retention-check-interval

The interval at which retention policies are checked and enforced. Enter as a human-readable time–for example: `30m` or `1h`.

**Default:** `30m`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --retention-check-interval | INFLUXDB3_RETENTION_CHECK_INTERVAL |

#### delete-grace-period

Specifies the grace period before permanently deleting data.

**Default:** `24h`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --delete-grace-period | INFLUXDB3_DELETE_GRACE_PERIOD |

#### hard-delete-default-duration

Sets the default duration for hard deletion of data.

**Default:** `90d`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --hard-delete-default-duration | INFLUXDB3_HARD_DELETE_DEFAULT_DURATION |

### Telemetry

-   [disable-telemetry-upload](#disable-telemetry-upload)
-   [telemetry-endpoint](#telemetry-endpoint)

#### disable-telemetry-upload

Disables the upload of telemetry data to InfluxData.

**Default:** `false`

| influxdb3 serve option | Environment variable |
| --- | --- |
| --disable-telemetry-upload | INFLUXDB3_TELEMETRY_DISABLE_UPLOAD |

#### telemetry-endpoint

Specifies the endpoint for telemetry data uploads.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --telemetry-endpoint | INFLUXDB3_TELEMETRY_ENDPOINT |

### TCP Listeners

-   [tcp-listener-file-path](#tcp-listener-file-path)
-   [admin-token-recovery-tcp-listener-file-path](#admin-token-recovery-tcp-listener-file-path)

#### tcp-listener-file-path

Specifies the file path for the TCP listener configuration.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --tcp-listener-file-path | INFLUXDB3_TCP_LISTINER_FILE_PATH |

#### admin-token-recovery-tcp-listener-file-path

Specifies the TCP listener file path for admin token recovery operations.

| influxdb3 serve option | Environment variable |
| --- | --- |
| --admin-token-recovery-tcp-listener-file-path | INFLUXDB3_ADMIN_TOKEN_RECOVERY_TCP_LISTENER_FILE_PATH |