influxdata/influxdb · error · Error

Python environment initialization failed

Error message

Python environment initialization failed: {0}
Please ensure Python and pip package manager is installed

What it means

Wraps a PluginEnvironmentError from influxdb3_processing_engine raised while initializing the Python environment used by the embedded processing engine (Python plugins). The message additionally hints that Python and pip must be installed.

Solutions

1. Install Python 3 and pip on the host (e.g. apt install python3 python3-pip python3-venv).
2. Read the chained PluginEnvironmentError for the exact failing step and fix accordingly.
3. Ensure the plugin environment directory is writable and not blocked by policy.
4. Disable the Python processing engine if plugins are not needed.

Example fix

# before (container without python)
FROM ubuntu
RUN apt-get install -y influxdb3
# after
RUN apt-get install -y python3 python3-pip python3-venv

which python3 >/dev/null && python3 -m pip --version \
  || { echo 'Python 3 and pip are required for the processing engine'; exit 1; }

match serve_result {
    Err(Error::PythonEnvironmentInitialization(src)) => {
        eprintln!("Python env init failed: {src}; install python3 + pip");
    }
    ...
}

When it happens

Trigger: `influxdb3 serve` starts with the processing engine enabled and Python interpreter/plugin-environment setup fails: missing python3 binary, missing pip/venv, or failure creating/activating the plugin virtualenv.

Common situations: Hosts without Python installed, minimal containers lacking pip or venv, wrong python version, or a read-only/blocked plugin environment directory.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Failed to import plugin module
• Plugin error
• {0}
• At least one field is required
• CA certificate PEM should be valid

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/eff490f688427aa5. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3/src/commands/serve.rs:176

    #[error("lost admin token recovery service")]
    LostAdminTokenRecovery,

    #[error("tls requires both a cert and a key file to be passed in to work")]
    NoCertOrKeyFile,

    #[error("table cache index initialization failed: {0}")]
    TableIndexCacheInitialization(
        #[source] influxdb3_write::table_index_cache::TableIndexCacheError,
    ),

    #[error(
        "environment variable {0} (named by --node-id-from-env / INFLUXDB3_NODE_ID_FROM_ENV) \
        must be set to a valid node id"
    )]
    NodeIdEnvVarMissing(String),

    #[error(
        "Python environment initialization failed: {0}\nPlease ensure Python and pip package manager is installed"
    )]
    PythonEnvironmentInitialization(
        #[source] influxdb3_processing_engine::environment::PluginEnvironmentError,
    ),
}

pub type Result<T, E = Error> = std::result::Result<T, E>;

// variable name and migration message tuples
const DEPRECATED_ENV_VARS: &[(&str, &str)] = &[(
    "INFLUXDB3_PARQUET_MEM_CACHE_SIZE_MB",
    "use INFLUXDB3_FILE_CACHE_SIZE instead, with a unit suffix (e.g. 500mb) or a percentage",
)];

const MIN_REPLAY_PRELOAD_CONCURRENCY: usize = 10; // the min number of files that will be held in memory

// Core catalog limits. The shared catalog crate's `CatalogLimits` defaults are

View on GitHub (pinned to 06200ef96b)