🚨 Ansible Error: 'to use the ssh connection type with passwords, you must install the sshpass program' — Cause, Fix, and Troubleshooting Guide

Overview

Ansible cannot type an SSH password by itself. When you tell it to authenticate with a password (via --ask-pass, ansible_password, or ansible_ssh_pass), it shells out to the sshpass helper to feed the password to OpenSSH non-interactively. If sshpass is not on the control node, the run aborts immediately:

ERROR! to use the 'ssh' connection type with passwords or pkcs11_provider, you must install the sshpass program

This is a control-node tooling problem, not a remote-host problem. Nothing has run on the target yet.

Symptoms

• The play fails before Gathering Facts, on the very first connection.
• It only happens when password auth is in play (-k, --ask-pass, or an ansible_password var); key-based hosts are unaffected.
• The same inventory works from a colleague’s machine that has sshpass installed.

ansible web-01 -i inventory.ini -m ping --ask-pass

SSH password:
ERROR! to use the 'ssh' connection type with passwords or pkcs11_provider, you must install the sshpass program

Common Root Causes

1. sshpass is not installed on the control node

The most common cause. Ansible found a password to use but no binary to deliver it.

2. Password auth set implicitly in inventory

An ansible_password or ansible_ssh_pass in group_vars/inventory silently forces password auth even when you expected key-based login.

3. sshpass installed but not on PATH

Installed in a non-standard prefix (or inside a virtualenv/container) so Ansible’s PATH never sees it.

How to diagnose

Confirm whether sshpass exists on the control node:

which sshpass || echo "sshpass NOT found"

Check what auth Ansible is actually using for the host:

ansible-inventory -i inventory.ini --host web-01 | grep -iE 'password|ssh_pass|private_key'

If you see ansible_password / ansible_ssh_pass, password auth is in effect and sshpass is required.

Fixes

Install sshpass (control node)

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y sshpass

# RHEL/Rocky/Alma (EPEL)
sudo dnf install -y epel-release && sudo dnf install -y sshpass

# macOS control node
brew install hudochenkov/sshpass/sshpass

Re-run:

ansible web-01 -i inventory.ini -m ping --ask-pass

web-01 | SUCCESS => {"changed": false, "ping": "pong"}

Preferred: switch to key-based auth and drop the password

Password automation is fragile and hits host-key-checking friction. Deploy a key and remove the password var:

ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@10.0.4.21

# group_vars/web.yml
ansible_user: deploy
ansible_ssh_private_key_file: ~/.ssh/id_ed25519
# remove any ansible_password / ansible_ssh_pass

If sshpass is installed but not found, fix PATH

sudo ln -s "$(command -v sshpass)" /usr/local/bin/sshpass   # if needed

What to watch out for

• With password auth, Ansible also refuses to connect to a host whose key it has not seen unless host key checking is handled — you may next hit Host Key checking is enabled and sshpass does not support this. Add the host to known_hosts or set StrictHostKeyChecking=accept-new.
• Never commit plaintext ansible_password to source control. If you must store a password, put it in Ansible Vault.
• In CI images, sshpass is rarely preinstalled — bake it into the image or, better, use keys and avoid the dependency entirely.

Related

• Ansible Error: ‘Permission denied (publickey)’
• Ansible Error: ‘Host key verification failed’
• Ansible Error: ‘UNREACHABLE! Failed to connect to the host via ssh’