n8n-sdk-python

[ English | 繁體中文 ]

This is an unofficial Python SDK for the n8n workflow automation platform. This SDK provides convenient wrappers for interacting with the n8n API, allowing you to manage workflows, executions, credentials, and other n8n resources from your Python applications.

Table of Contents

• System Requirements
• Installation
• Initial Setup
• Quick Start
• Troubleshooting
• Contributing
• License

System Requirements

Before installing n8n-sdk-python, please ensure your system meets the following requirements:

• Python 3.8 or higher
• A running n8n instance (local or remote)
• n8n API key (for authentication)

Installation

Using a Virtual Environment

Using a virtual environment can prevent dependency conflicts:

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

Method 1: Using pip (Recommended)

The easiest way to install is using the pip package manager:

pip install n8n-sdk-python

Method 2: Installing from Source

If you need the latest development version or want to modify the code, you can install from source:

# Clone the repository
git clone https://github.com/eric050828/n8n-sdk-python.git
cd n8n-sdk-python

# Install in development mode
pip install -e .

Initial Setup

After installation, you need to perform some initial setup to use the SDK.

Get n8n API Key

1. Log in to your n8n instance.
2. Click on the user icon in the upper right corner and select "Settings".
3. Click on the "API" tab.
4. Click the "Create" button to generate a new API key.
5. Copy the generated API key (please save it, as it will only be displayed once).

Set Environment Variables

You can configure the SDK through environment variables, so you don't need to hardcode sensitive information in your code:

On Linux/macOS

export N8N_BASE_URL="http://localhost:5678"
export N8N_API_KEY="your-api-key-here"

On Windows

set N8N_BASE_URL=http://localhost:5678
set N8N_API_KEY=your-api-key-here

Using a .env File

For project development, it is recommended to use a .env file to manage environment variables:

1. Create a file named .env in your project root directory.
2. Add the following content:

N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your-api-key-here

3. Load these settings in your program:

from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

# Now you can use os.getenv to get environment variables
base_url = os.getenv("N8N_BASE_URL")
api_key = os.getenv("N8N_API_KEY")

Please note that you need to install the python-dotenv library to use this feature: pip install python-dotenv

Quick Start

After installation, you can run the following code to verify that the SDK is working correctly:

import asyncio
from n8n_sdk_python import N8nClient
from n8n_sdk_python.models.workflows import WorkflowList

async def test_connection():
    # Initialize the client
    client = N8nClient(
        base_url="http://localhost:5678",  # Replace with your n8n instance URL
        api_key="your-api-key-here"  # Replace with your API key
    )
    
    try:
        # Try to get the workflow list
        workflows: WorkflowList = await client.list_workflows(limit=1)
        print("✅ Connection successful! Number of workflows found:", len(workflows.data))
        return True
    except Exception as e:
        print("❌ Connection failed:", str(e))
        return False

if __name__ == "__main__":
    result = asyncio.run(test_connection())
    print("Test result:", "Success" if result else "Failure")

Troubleshooting

If you encounter problems, here are some common issues and their solutions:

Installation Issues

Problem: "ERROR: Could not find a version that satisfies the requirement n8n-sdk-python" during installation.

Solution: Check if your Python version meets the requirements (3.8+) and ensure pip is updated to the latest version:

python --version
pip install --upgrade pip

Connection Issues

Problem: "Connection refused" error when connecting to the n8n instance.

Solution:

• Confirm that the n8n instance is running.
• Check if the URL is correct, including the protocol (http/https) and port.
• Ensure no firewall is blocking the connection.

Problem: Received a 401 Unauthorized error.

Solution:

• Confirm the API key is correct.
• Check if the API key has expired or been revoked.
• Verify that the user has sufficient permissions.

Import Issues

Problem: "ModuleNotFoundError: No module named 'n8n_sdk_python'"

Solution:

• Confirm the library is correctly installed: pip list | grep n8n-sdk-python
• If using a virtual environment, confirm it is activated: which python
• Try reinstalling: pip install --force-reinstall --no-cache-dir n8n-sdk-python

Other Issues

If you encounter other issues, you can:

1. Check the log output for detailed error messages.
2. Enable debug mode for more logs:

import logging
logging.basicConfig(level=logging.DEBUG)

3. Submit an issue on the GitHub repository with error details and steps to reproduce.