Python Function (Raw)

Run custom Python script once and return raw output (exitCode, stdout, stderr)

Overview

This node allows you to run custom Python scripts within an n8n workflow. It executes the provided Python code either once for all input items or separately for each item, and returns the raw output including exit code, standard output, and standard error. The node supports injecting variables such as input data and environment variables into the script, parsing the script output in various ways, and handling errors flexibly.

Common scenarios where this node is beneficial include:

  • Running complex data transformations or calculations that are easier or only possible in Python.
  • Integrating with Python libraries or APIs not directly supported by other nodes.
  • Executing custom automation logic that requires Python scripting.
  • Testing and debugging Python code snippets within workflows.

Practical examples:

  • Processing JSON data from previous nodes using Python’s json module.
  • Calling external APIs via Python requests library (with "Inject Variables" disabled).
  • Performing machine learning inference or data analysis on input data.
  • Generating reports or summaries based on workflow data.

Properties

Name Meaning
Python Code The Python script to execute. Can access injected variables if enabled. Example code is provided by default.
Inject Variables Whether to inject input_items (input data) and env_vars (environment variables) into the Python script as variables. Disable to run pure Python without these injections.
Python Executable Path or command name of the Python interpreter to use (e.g., python3, python, or full path).
Error Handling How to handle errors and non-zero exit codes from the Python script:
- Return Error Details: Continue execution and return error info as output.
- Throw Error: Stop workflow on error.
- Ignore Exit Code: Continue regardless of exit code except system errors.
Debug/Test Mode Controls debug information and testing behavior:
- Off: Normal execution.
- Basic Debug: Include script content and basic info.
- Full Debug: Add detailed metadata and timing.
- Test Only: Validate script without running.
- Export Script: Include script file as binary output.
Script Generation Options Collection of options controlling script generation:
- Include input_items Array: Include input data array.
- Include env_vars Dictionary: Include legacy dictionary of env vars.
- Hide Variable Values: Replace variable values with asterisks in generated script for security.
- System Environment Variables: Select which system env vars to include.
Parse Output How to parse the script's stdout output:
- None (Raw String): Return raw string.
- JSON: Parse as JSON object.
- Lines: Split into array of lines.
- Smart Auto-detect: Automatically detect JSON, CSV, or lines.
Parse Options Additional options when parsing JSON or smart output:
- Handle Multiple JSON Objects: Parse multiple JSON objects separated by newlines.
- Strip Non-JSON Text: Remove text before/after JSON.
- Fallback on Parse Error: Keep original output if parsing fails.
Execution Mode Choose how many times to execute the script:
- Once for All Items: Run script once with all input items.
- Once per Item: Run script separately for each input item.
Pass Through Input Data Whether to include original input data in the output alongside Python results.
Pass Through Mode How to include input data when pass through is enabled:
- Merge with Result: Add input fields directly to result.
- Separate Field: Add input data as inputData field.
- Multiple Outputs: Return separate items for input and Python result.

Output

The node outputs an array of items where each item contains a json property with the following structure:

  • exitCode: Integer exit code of the Python script.
  • stdout: Raw standard output string from the script.
  • stderr: Standard error output string.
  • success: Boolean indicating if exit code was zero.
  • error: Error message if any.
  • inputItemsCount: Number of input items processed.
  • executedAt: Timestamp of execution.
  • injectVariables: Boolean indicating if variables were injected.
  • parseOutput: The chosen output parsing mode.
  • executionMode: Execution mode used (once or perItem).

If output parsing is enabled (json, lines, or smart), additional fields may be present:

  • parsed_stdout: Parsed representation of stdout (object, array, or lines).
  • parsing_success: Boolean indicating if parsing succeeded.
  • parsing_error: Parsing error message if failed.
  • output_format: Format detected or parsed (json, csv, text, etc.).
  • parsing_method: Method used for parsing.

If debug or test modes are enabled, extra debug information is included such as:

  • script_content: The full Python script executed.
  • execution_command: Command line used to run the script.
  • debug_info: Metadata including timing, environment checks, syntax validation.
  • test_mode: Flag indicating test-only mode.
  • execution_skipped: Flag indicating execution was skipped.

If "Export Script" debug mode is selected, the Python script file is attached as a binary file in the output item(s).

If pass-through input data is enabled, the original input data is merged or added alongside the Python output according to the selected mode.

The node does not produce binary data from the Python script output itself, but can attach the script file as binary when exporting.

Dependencies

  • Requires a Python interpreter installed and accessible at the specified path.
  • Optionally uses environment variables and credentials injected into the script.
  • No external npm packages required; uses Node.js child process to spawn Python.
  • For advanced Python libraries (e.g., requests), user must ensure they are installed in the Python environment.
  • No internal credential names exposed; users provide API keys or environment variables generically.
  • No special n8n environment variables needed beyond standard credential/environment injection.

Troubleshooting

  • Common Issues:

    • Python executable path incorrect or Python not installed → script fails to run.
    • Syntax errors in Python code → script execution fails with syntax error details.
    • Missing Python modules → error messages indicate missing modules; install them in Python environment.
    • Output parsing errors → malformed or unexpected output causes parsing to fail; fallback option can help.
    • Large input data → running per item may be slow; consider running once for all items if possible.

  • Error Messages:

    • Process exited with code X: Indicates script returned non-zero exit code; check script logic.
    • ModuleNotFoundError: Missing Python package; install required packages.
    • SyntaxError: Python syntax error; fix code accordingly.
    • Could not generate temporary script file: File system permission or disk space issues.
    • System error: Node encountered an internal error; check logs and environment.

  • Resolutions:

    • Verify Python path and installation.
    • Test Python code independently outside n8n.
    • Enable debug modes to get detailed script and execution info.
    • Use "Test Only" mode to validate script without running.
    • Adjust error handling settings to control workflow behavior on errors.

Links and References

This summary is based solely on static analysis of the provided source code and property definitions.

Discussion