Run Fail2Ban's Helper with the Intended Python

You will verify what fail2ban-python actually invokes, then use it to run a short command, a module or a script with the same interpreter Fail2Ban expects. On this machine it is the Fail2Ban package's Python entry point, backed by Python 3.12.3 from package version 1.0.2-3ubuntu0.1. Allow about ten minutes. You need a shell and a normal user account; the examples do not require sudo.

1. Check the installed entry point

Start by resolving the command instead of guessing which Python is first in your PATH:

$ command -v fail2ban-python
/usr/bin/fail2ban-python
$ readlink -f /usr/bin/fail2ban-python
/usr/bin/python3.12
$ fail2ban-python --version
Python 3.12.3

The installed command is a symbolic link to the system Python executable. That is the practical meaning of this helper on this host: a Fail2Ban-specific name selects the interpreter used by the packaged tools. The manpage identifies the helper as version 1.0.2 and was generated in November 2022; the package revision and interpreter version above are local facts and can differ on another release.

Checkpoint: if command -v finds nothing, stop here. Do not replace the missing command with an arbitrary virtual-environment Python when diagnosing a packaged Fail2Ban installation. Check the package installation and the executable search path through your normal system-management process.

2. Confirm the interpreter from inside Python

A version string is useful, but a small introspection command also shows the executable name Python reports to the running program:

$ fail2ban-python -c 'import sys; print(sys.executable); print(sys.version_info[0])'
/usr/bin/fail2ban-python
3

The -c option takes Python source as its next argument and ends the interpreter's option list. The command prints fail2ban-python for sys.executable because that is the name used to start it, even though the link resolves to /usr/bin/python3.12. The second line confirms that this installation is Python 3.

Keep shell quoting around the code. Without single quotes, the shell can expand characters before Python receives them. This is a read-only check and does not need elevated privileges.

3. Run a module with -m

Use -m when the thing you want to run is an importable Python module rather than a file path. The module name has no .py suffix:

$ fail2ban-python -m site --user-site
/home/andy/.local/lib/python3.12/site-packages

This example asks the standard-library site module to print the current user's site-packages directory. It is a harmless way to check module lookup. In a real Fail2Ban diagnostic, substitute a module that the installed package documents, and keep the same fail2ban-python -m ... prefix.

Arguments after the module name belong to that module. Do not put interpreter options after -m and expect them to affect Python; the option terminates the interpreter option list.

4. Run a script or standard input

For a script on disk, pass its path followed by the script's arguments:

$ fail2ban-python /path/to/check.py --verbose

The path is a placeholder. Replace it with a readable script you have reviewed. Running a file executes its Python code, so treat an unfamiliar script as executable code, not as a harmless data file. If the code is arriving through a pipe, use - explicitly:

$ printf '%s\n' 'print("stdin-ok")' | fail2ban-python -
stdin-ok

With a terminal and no script, Python enters interactive mode. That is useful for exploration, but it is an easy distraction in an incident. For repeatable checks, prefer a reviewed file or a short -c command and capture the exit status immediately afterwards.

5. Use the safety-related interpreter options deliberately

The helper exposes Python interpreter options, not Fail2Ban jail or ban settings. A few options are useful when troubleshooting:

• -V or --version prints the Python version and exits.
• -h or --help prints the available options and exits.
• -B prevents imports from writing .pyc bytecode files.
• -E ignores PYTHON* environment variables such as PYTHONPATH.
• -I uses isolated mode, which also ignores those variables and the user site-packages directory.
• -u makes standard output and standard error unbuffered, which can help when a diagnostic is being collected by another process.

Prefer -I when you need to test whether a result depends on the caller's Python environment. Do not add it automatically to a Fail2Ban service command: isolation changes module search and can make locally installed dependencies invisible. The official Python command-line documentation describes the current interpreter options; the local manpage is the authority for the installed helper's displayed interface.

6. Keep Fail2Ban configuration separate

fail2ban-python does not start the Fail2Ban server, inspect jails or edit files under /etc/fail2ban. The options in its manpage are Python options. If you need to inspect Fail2Ban itself, use the appropriate Fail2Ban command and its own documentation. Mixing the two command families is a common error: passing a jail name or a client option to this helper will be interpreted as Python input or a script path.

Do not use sudo merely to run --version, -c, -m or a read-only diagnostic. Use elevated privileges only when the separate script genuinely needs access that your account lacks, and review that script first. Running arbitrary Python as root turns a small diagnostic into a system-wide change risk.

7. Recover from a wrong interpreter choice

If a diagnostic fails with an import error, first compare the two interpreters rather than changing packages:

$ fail2ban-python -c 'import sys; print(sys.executable); print(sys.path[0])'
$ python3 -c 'import sys; print(sys.executable); print(sys.path[0])'

Different executable paths or search paths can explain why one command sees a module and the other does not. Re-run the failing check with fail2ban-python, then inspect the package and environment deliberately. Do not "fix" a system installation by creating a replacement symlink in /usr/bin, deleting bytecode trees, or reinstalling packages blindly. Those actions can affect running services and are not required by this helper.

If you changed only a temporary test command, recovery is simply to close the shell or remove the temporary test file you created. The examples above change no Fail2Ban configuration and restart no service.