n8n - 💡(How to fix) Fix ## Bug: Python Task Runner fails on native npm install — `src/` folder missing from published package

Bug Description

Bug: Python Task Runner fails on native npm install — src/ folder missing from published package

Environment

• n8n version: 2.21.7
• Install method: Global npm (sudo npm install -g n8n)
• OS: Ubuntu 24 (Linux, native install — not Docker)
• Node.js version: (add yours)
• Python version: 3.12.3

To Reproduce

What happened

After installing n8n globally via npm and starting it, the Python task runner fails with:

Failed to start Python task runner in internal mode. because its virtual environment is missing from this system.

Creating the venv at ~/.n8n/runner-venvs/python (as suggested in the docs) does not fix the issue.

Root cause (after investigation)

After digging into the source, I found two problems:

1. Wrong venv path /usr/lib/node_modules/n8n/dist/task-runners/task-runner-process-py.js resolves the venv path as:

const pythonDir = path.join(__dirname, '../../../@n8n/task-runner-python');
// resolves to: /usr/lib/node_modules/@n8n/task-runner-python/.venv/bin/python

This is outside the n8n package folder entirely, so the venv created at ~/.n8n/runner-venvs/python is never found.

2. src/ Python source files are not included in the npm release The @n8n/task-runner-python package published to npm does not include the src/ folder (the actual Python runner code). It only contains a .venv with pip. So even after creating the venv at the correct path, n8n fails with:

ModuleNotFoundError: No module named 'src'

Expected behavior

Workaround

# 1. Create the directory n8n actually looks in
sudo mkdir -p /usr/lib/node_modules/@n8n/task-runner-python

# 2. Copy the source from inside n8n's own node_modules
sudo cp -r /usr/lib/node_modules/n8n/node_modules/@n8n/task-runner-python/. \
    /usr/lib/node_modules/@n8n/task-runner-python/

# 3. Clone the repo to get the missing src/ folder
git clone --depth 1 https://github.com/n8n-io/n8n.git /tmp/n8n-src
sudo cp -r /tmp/n8n-src/packages/@n8n/task-runner-python/src \
    /usr/lib/node_modules/@n8n/task-runner-python/

# 4. Create venv and install dependencies
sudo rm -rf /usr/lib/node_modules/@n8n/task-runner-python/.venv
sudo python3 -m venv /usr/lib/node_modules/@n8n/task-runner-python/.venv
sudo /usr/lib/node_modules/@n8n/task-runner-python/.venv/bin/pip install websockets

After this, the Python Task Runner registers successfully.

Debug Info

Suggested fix

One or more of the following:

• Include the src/ folder in the files field of packages/@n8n/task-runner-python/pyproject.toml so it is published with the package
• Update the error message to give actionable guidance for native installs (not just Docker)
• Document the native Linux setup steps in https://docs.n8n.io/hosting/configuration/task-runners/

Additional notes

The @n8n/task-runner-python package also requires Python >=3.13 in pyproject.toml, but works fine on Python 3.12 when dependencies are installed manually. This may also be worth revisiting.

Happy to submit a PR for any of the above if maintainers can point me to the right approach.

Operating System

Ubuntu 24 (Linux, native install — not Docker)

n8n Version

• n8n version: 2.21.7

Node.js Version

Node.js version: 24

Database

SQLite (default)

Execution mode

main (default)

Hosting

self hosted