Paramiko Deprecated for network_cli: Migrate to libssh (ansible-pylibssh)

Introduction

As of May 2026, Paramiko has been officially deprecated for network_cli connections in the Ansible ecosystem. Ansible's direction for SSH connectivity is OpenSSH and libssh, not Paramiko. This deprecation affects anyone using Ansible for network automation with Cisco, Arista, Juniper, and other network devices.

Paramiko support in network_cli will be removed any time after February 1, 2028. This guide walks you through the migration process.

See also: Ansible Troubleshooting: SSH Connection Issues - Complete Fix Guide (2026)

Why Is Paramiko Being Deprecated?

Paramiko is a pure-Python SSH implementation that has served Ansible well, but it has limitations compared to native SSH libraries: • Performance: libssh and OpenSSH are significantly faster for large-scale network automation • Security: OpenSSH and libssh receive more frequent security updates and audits • Compatibility: libssh better supports modern SSH features and algorithms • Maintenance: Consolidating on fewer SSH backends simplifies the Ansible codebase

Prerequisites

Before migrating, ensure you have: • Ansible Core 2.15 or later (recommended: latest stable release) • ansible.netcommon collection 5.0.0 or later • Python 3.9 or later • C compiler and libssh development headers for building ansible-pylibssh

See also: AAP 2.6 Migration from AWX: Complete Upgrade and Data Migration Guide

Step 1: Install ansible-pylibssh

# Install ansible-pylibssh
pip install ansible-pylibssh
# Verify installation
python -c "import pylibsshext; print(pylibsshext.__version__)"

On some systems, you may need development libraries:

# RHEL/CentOS/Fedora
sudo dnf install libssh-devel gcc python3-devel
# Debian/Ubuntu
sudo apt install libssh-dev gcc python3-dev
# macOS
brew install libssh

Step 2: Update ansible.cfg

# ansible.cfg
[persistent_connection]
# Optional: set the SSH type globally
ssh_type = libssh

See also: AAP 2.6 RPM Deprecation — Planning Your Containerized Migration

Step 3: Update Inventory Variables

# group_vars/network.yml
ansible_connection: ansible.netcommon.network_cli
ansible_network_cli_ssh_type: libssh
# Per-platform examples
# Cisco IOS
ansible_network_os: cisco.ios.ios
# Arista EOS
ansible_network_os: arista.eos.eos
# Juniper Junos
ansible_network_os: junipernetworks.junos.junos

Step 4: Update Playbooks

If you explicitly set ansible_ssh_private_key_file or other SSH parameters, ensure they work with libssh:

---
- name: Network automation with libssh
  hosts: network_devices
  gather_facts: false
  vars:
    ansible_connection: ansible.netcommon.network_cli
    ansible_network_cli_ssh_type: libssh
    ansible_network_os: cisco.ios.ios
tasks:
    - name: Gather device facts
      cisco.ios.ios_facts:
        gather_subset:
          - all
      register: device_facts
- name: Display hostname
      ansible.builtin.debug:
        msg: "Device hostname: {{ device_facts.ansible_facts.ansible_net_hostname }}"
- name: Backup running configuration
      cisco.ios.ios_config:
        backup: true
      register: backup_result

Step 5: Test Your Migration

Run your existing playbooks in check mode to verify compatibility:

# Test with verbose output to see connection details
ansible-playbook -i inventory network_backup.yml --check -vvv
# Look for connection messages showing libssh
# You should see: "ssh type is set to libssh"

Troubleshooting Common Issues

Error: "No module named 'pylibsshext'"

# Ensure ansible-pylibssh is installed in the correct Python environment
pip install --upgrade ansible-pylibssh
# If using a virtual environment, activate it first
source /path/to/venv/bin/activate
pip install ansible-pylibssh

Error: "libssh shared library not found"

# Set the library path if needed
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
# Or install libssh system-wide
# RHEL: sudo dnf install libssh
# Ubuntu: sudo apt install libssh-4

SSH Key Authentication Fails

# Ensure key format is compatible with libssh
# Convert old-format keys if needed:
# ssh-keygen -p -m PEM -f ~/.ssh/id_rsa
# In inventory, use explicit key path:
ansible_ssh_private_key_file: ~/.ssh/id_rsa

Known Differences Between Paramiko and libssh

| Feature | Paramiko | libssh | |---|---|---| | SSH Agent forwarding | Supported | Supported | | ProxyCommand | Limited | Full support | | Ed25519 keys | Supported | Supported | | FIPS mode | Partial | Full support | | Performance | Slower | Faster |

Migration Checklist

• [ ] Install ansible-pylibssh on all control nodes • [ ] Update ansible.cfg with ssh_type = libssh • [ ] Update inventory ansible_network_cli_ssh_type: libssh • [ ] Test all playbooks in check mode • [ ] Verify SSH key compatibility • [ ] Update CI/CD pipelines with new dependency • [ ] Update execution environments to include ansible-pylibssh • [ ] Remove Paramiko from requirements after verification • [ ] Document the change for your team

Timeline

| Date | Action | |---|---| | May 2026 | Deprecation announced | | Now → Jan 2028 | Migration window | | After Feb 1, 2028 | Paramiko support removed from network_cli |

FAQ

Will this affect non-network connections?

No. This deprecation only affects network_cli connections. Standard SSH connections via ansible.builtin.ssh are not affected — they already use OpenSSH.

Can I still use Paramiko for other purposes?

Paramiko remains available as a Python library. The deprecation is specifically for its use as the SSH transport for Ansible's network_cli connection plugin.

What about execution environments?

Update your execution environment definitions to include ansible-pylibssh:

# execution-environment.yml
dependencies:
  python:
    - ansible-pylibssh>=1.2.0
  system:
    - libssh-devel [platform:centos-9 platform:rhel-9]
    - libssh-dev [platform:debian platform:ubuntu]

Is ansible-pylibssh available for all platforms?

ansible-pylibssh supports Linux (x86_64, aarch64), macOS (Intel and Apple Silicon), and most platforms where libssh can be compiled.

Conclusion

Migrating from Paramiko to libssh is straightforward and brings performance and security improvements. With nearly two years before the removal deadline, there is ample time to test and validate. Start your migration now to avoid last-minute issues.

Related Articles

• Ansible Connection Types: SSH, WinRM, Local, Docker, Network Guide • Ansible Network Automation: Cisco, Arista, Juniper at Scale • Ansible Troubleshooting SSH Connection Issues • Ansible SSH Authentication Setup Guide