External Python runner, without a container

lost_ghost · June 3, 2026, 8:46pm

Describe the problem/error/question

I’m trying to setup an external python runner without using a container.

I followed the Task runners guide ( Task runners | n8n Docs ) but I installed the launcher application ( GitHub - n8n-io/task-runner-launcher: CLI utility to launch an n8n task runner in external mode · GitHub ) locally.
I Installed a python runner,
❯ pip list | grep python-runner
python-runner 0.6.1

task-runners.json
{
“task-runners”: [
{
“runner-type”: “python”,
“workdir”: “/home/user/n8n-files/”,
“command”: “/usr/bin/python3”,
“args”: [ “-m”, “python-runner” ],
“health-check-server-port”: “5681”
}
]
}

When i run the launcher application the output is stuck at ,
INFO [launcher:py] Waiting for task broker to be ready…
INFO [launcher:py] Waiting for launcher’s task offer to be accepted…

if i start an n8n workflow I see the errors,
ERROR [runner:py] /usr/bin/python3: No module named python-runner
ERROR [launcher:py] Runner process exited with error: exit status 1

I don’t believe it has to do with env. variables, because I have them in /etc/environment, but I also tried adding them in task-runners.json

I’m sure I’m missing something obvious here. Is it the wrong runner?

What is the error message (if any)?

./task-runner-launcher python
INFO Starting launcher’s health check server at port 5680
INFO [launcher:py] Starting launcher goroutine…
WARN DEPRECATION WARNING: N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT will no longer be automatically passed to runners in a future version. Please add this env var to ‘allowed-env’ or use ‘env-overrides’ in your task runner config to maintain current behavior.
WARN DEPRECATION WARNING: N8N_RUNNERS_TASK_TIMEOUT will no longer be automatically passed to runners in a future version. Please add this env var to ‘allowed-env’ or use ‘env-overrides’ in your task runner config to maintain current behavior.
INFO [launcher:py] Waiting for task broker to be ready…
INFO [launcher:py] Waiting for launcher’s task offer to be accepted…
ERROR [runner:py] /usr/bin/python3: No module named python-runner
ERROR [launcher:py] Runner process exited with error: exit status 1

Share the output returned by the last node

N/A

Information on your n8n setup

n8n version: 2.23.2
Database (default: SQLite): N/A
n8n EXECUTIONS_PROCESS setting (default: own, main):
Running n8n via (Docker, npm, n8n cloud, desktop app): npm
Operating system: Cachy OS

akingbade-Samuel · June 3, 2026, 10:18pm

Got it! So you want me to rewrite that same reply but make it look less AI and more human. Here it is:

The fix is actually simpler than you think it’s just a typo in your config.

Your args have "python-runner" with a hyphen, but Python’s -m flag doesn’t accept hyphens in module names. Change it to an underscore:

"args": [ "-m", "python_runner" ]

That’s literally all that’s causing the No module named python-runner error.

Before restarting, just run this quickly to confirm everything is pointing to the right place:

/usr/bin/python3 -m python_runner --help

If that works in your terminal, you’re done. If it fails, your package was probably installed under a different Python environment. Fix it with:

/usr/bin/python3 -m pip install python-runner

Then try again and it should work.

Oh and those Waiting for task broker messages are completely normal that’s just the launcher waiting for n8n to connect, nothing broken there.

Let me know how it goes.

lost_ghost · June 3, 2026, 11:19pm

That is a good catch!

Now in the launcher application is giving me,

ERROR [runner:py] /usr/bin/python3: No module named python_runner.main; ‘python_runner’ is a package and cannot be directly executed
2026/06/03 19:09:15 ERROR [launcher:py] Runner process exited with error: exit status 1

and the reason is this,
❯ /usr/bin/python3 -m python_runner --help
Traceback (most recent call last):
File “”, line 194, in _run_module_as_main
File “”, line 164, in _get_module_details
File “”, line 893, in get_code
File “”, line 823, in source_to_code
File “”, line 491, in _call_with_frames_removed
File “/home/user/Templates/n8n_python_runner/python_runner.py”, line 8
self.send_response(200); self.end_headers(); self.wfile.write(b"OK") else:
^^^^
SyntaxError: invalid syntax

Is this the wrong task-runner? Can I use the npm package @n8n/task-runner?

Thanks you !

EDIT;

You got flagged because you sounded like an AI?
This post was sitting on “Pending’” for a day. Moderation is pretty strict around here!

EDIT 2;
I also tried to install n8n Python runner that is included in the Docker image from the guide.
pip install git+https://github.com/n8n-io/n8n.git@master#subdirectory=packages/@n8n/task-runner-python

The package is not even seen by python. I guess it’s part of the larger n8n package.

SE-automations · June 4, 2026, 8:44am

Python is not running the library you got with pip. It is finding a file in your directory called python_runner.py. Trying to run that instead. This file has a mistake on line 8, I think. That is why it is crashing.

The Fix:

Rename the file python_runner.py in the /home/user/Templates/n8n_python_runner directory to something like my_test_runner.py.

When you do this Python will look for the library you installed and use that of the local file. Try this. See what happens. Python will then run the library you installed with pip not the local python_runner.py file. This should fix the problem, with Python not running the library you installed.

lost_ghost · June 4, 2026, 3:10pm

I’ve created a venv and pip install python-runner. From inside the venv,
venv❯ python3 -c “import python_runner; print(‘Success’)”
Success

n8n-task-runners.json
{
“task-runners”: [
{
“runner-type”: “python”,
“workdir”: “/home/user/.n8n-files/”,
“command”: “/home/user/Templates/n8n_python_runner/venv/bin/python3”,
“args”: [ “/home/user/Templates/n8n_python_runner/venv/lib/python3.14/site-packages/python_runner/runner.py” ],
“health-check-server-port”: “5681”
}
]
}

./task-runner-launcher python
INFO [launcher:py] Waiting for task broker to be ready…
INFO [launcher:py] Waiting for launcher’s task offer to be accepted…
ERROR [runner:py] Traceback (most recent call last):
ERROR [runner:py] File “/home/kc/Templates/n8n_python_runner/venv/lib/python3.14/site-packages/python_runner/runner.py”, line 13, in
ERROR [runner:py] from .output import OutputBuffer
ERROR [runner:py] ImportError: attempted relative import with no known parent package
ERROR [launcher:py] Runner process exited with error: exit status 1

Progress???

houda_ben · June 4, 2026, 3:50pm

@lost_ghost Hello !

the core issue: python-runner from PyPI is not the n8n Python task runner. That’s a different, unrelated package. The real n8n Python runner isn’t published to PyPI, which is why your earlier pip install from the repo didn’t work either.

Without Docker, your only path is cloning the n8n repo and setting up the runner from source:

git clone https://github.com/n8n-io/n8n.git
cd n8n/packages/@n8n/task-runner-python
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Then point your task-runners.json at that venv with entry point -m src.main. This is unsupported territory though, the docs only cover the Docker-based setup.

Let me know if it works !

lost_ghost · June 5, 2026, 4:19pm

./task-runner-launcher python
INFO [launcher:py] Waiting for task broker to be ready…
2026/06/04 12:38:50 INFO [launcher:py] Waiting for launcher’s task offer to be accepted…
2026/06/04 12:39:08 INFO [launcher:py] Runner process exited on idle timeout
2026/06/04 12:39:08 INFO [launcher:py] Waiting for task broker to be ready…
2026/06/04 12:39:08 INFO [launcher:py] Waiting for launcher’s task offer to be accepted…

In n8n GUI I get error,
Security violations detected

I’m not sure what security violations those might be.

houda_ben · June 6, 2026, 8:18am

@lost_ghost

Your runner is actually working now and the idle timeout cycle in the logs is normal, the launcher shuts down the runner when idle and restarts it on demand.

The “Security violations detected” error means the sandbox is blocking Python stdlib imports by default.

Add env-overrides to your task-runners.json:

{
  "runner-type": "python",
  "workdir": "/home/user/.n8n-files/",
  "command": "/path/to/n8n/packages/@n8n/task-runner-python/.venv/bin/python3",
  "args": ["-I", "-B", "-X", "disable_remote_debug", "-m", "src.main"],
  "health-check-server-port": "5681",
  "env-overrides": {
    "N8N_RUNNERS_STDLIB_ALLOW": "*",
    "N8N_RUNNERS_EXTERNAL_ALLOW": "*"
  }
}

Let me know if this clears the secutity error !

lost_ghost · June 7, 2026, 4:42pm

(post deleted by author)

lost_ghost · June 8, 2026, 12:11am

Yep, that resolved the issue. Thank you! This has put me on hold for a week now.

Topic		Replies	Views
N8N npm tasker runner set up help Questions	9	1149	January 29, 2026
Code node (python) Questions	2	350	April 5, 2026
Struggling with External Runners image Questions	2	928	April 20, 2026
External Task Runner v2.4.8: error when launching runner process Questions	4	622	May 5, 2026
Python Node not working in my n8n(self-hosted) Questions	2	2090	March 31, 2026

External Python runner, without a container

Describe the problem/error/question

What is the error message (if any)?

Share the output returned by the last node

Information on your n8n setup

Related topics