Install & Compatibility
Where this runs
tested against v0.16.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.849s · 42.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.9s · import 0.759s · 43MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SCPClient
✓ from scp import SCPClient
This is the primary class for SCP file transfer operations.
SSHClient
✓ from paramiko import SSHClient
While part of `paramiko`, `SSHClient` is essential for establishing the underlying SSH connection that `SCPClient` uses.
This quickstart demonstrates how to establish an SSH connection using `paramiko.SSHClient` and then use `scp.SCPClient` to upload and download a file. It includes important considerations for host key policy and proper connection closure.
import os
from paramiko import SSHClient, AutoAddPolicy
from scp import SCPClient
# Configuration from environment variables for security
HOSTNAME = os.environ.get('SCP_HOSTNAME', 'your_remote_host')
USERNAME = os.environ.get('SCP_USERNAME', 'your_username')
PASSWORD = os.environ.get('SCP_PASSWORD', '') # Use SSH keys in production
local_file = 'local_test_file.txt'
remote_path = '/tmp/remote_test_file.txt'
# Create a dummy local file for the example
with open(local_file, 'w') as f:
f.write('Hello from scp.py!')
ssh = SSHClient()
# Set policy to auto-add host keys for demo. In production, use ssh.load_system_host_keys() or HostKeys().add().
ssh.set_missing_host_key_policy(AutoAddPolicy())
try:
# Connect to the remote server
ssh.connect(hostname=HOSTNAME, username=USERNAME, password=PASSWORD, port=22)
print(f"Connected to {HOSTNAME}")
# SCPCLient takes a paramiko transport as an argument
with SCPClient(ssh.get_transport()) as scp:
# Upload a file
scp.put(local_file, remote_path)
print(f"Uploaded '{local_file}' to '{remote_path}'")
# Download the file back to verify
downloaded_file = 'downloaded_test_file.txt'
scp.get(remote_path, downloaded_file)
print(f"Downloaded '{remote_path}' to '{downloaded_file}'")
except Exception as e:
print(f"An error occurred: {e}")
finally:
ssh.close()
print("SSH connection closed.")
# Clean up dummy files
import os
if os.path.exists(local_file):
os.remove(local_file)
if os.path.exists(downloaded_file):
os.remove(downloaded_file)
scp --version
Debug
Known issues
gotchaThe `scp` library is a thin wrapper around `paramiko`. Therefore, `paramiko` and its dependencies (like `cryptography`, which might require compilation tools) must be correctly installed. Issues with `paramiko` often manifest as `scp` problems.fixEnsure `paramiko` is installed (`pip install paramiko`) and resolve any underlying `cryptography` installation errors, which might require system-level development packages.
affects: All versions
gotchaFor security, always verify host keys. Using `paramiko.AutoAddPolicy()` in production is dangerous as it makes your client vulnerable to man-in-the-middle attacks.fixPrefer `ssh.load_system_host_keys()` or manually add host keys to a `paramiko.HostKeys` object. Implement strict host key checking and handle `paramiko.BadHostKeyException`.
affects: All versions
deprecatedThe underlying SCP1 protocol has known security limitations and is considered deprecated by OpenSSH in favor of SFTP. While `scp.py` implements SCP1, be aware that future changes in OpenSSH servers might affect compatibility or expose vulnerabilities.fixFor new projects or if advanced file transfer features are needed, consider using `paramiko`'s built-in SFTP client (`ssh.open_sftp()`) or higher-level libraries like `Fabric` that might use SFTP.
affects: All versions
breakingThe `progress` callback signature changed in version 0.13.0. It reverted to accepting 3 arguments (`path`, `total_size`, `sent_size`). A new `progress4` parameter was introduced to accept 4 arguments, including `peername`. Code using the 4-argument `progress` callback from pre-0.13.0 versions will break.fixUpdate your progress callback functions to match the 3-argument signature for `progress`, or use the `progress4` parameter if you require the `peername` argument. Review the `CHANGELOG.md` for specific details.
affects: <0.13.0 to 0.13.0
gotchaPrior to version 0.13.6, the `put()` method might have behaved unexpectedly when the source directory path had a trailing slash (e.g., `scp.put('my_dir/', remote_path)`).fixUpgrade to `scp` version 0.13.6 or newer. If upgrading is not possible, ensure source directory paths passed to `put()` do not have trailing slashes if you intend to copy the directory itself rather than its contents.
affects: <0.13.6
gotchaAttempts to establish an SCP connection can fail with `[Errno -2] Name does not resolve` if the provided hostname or IP address is invalid, misspelled, or cannot be resolved by the system's DNS configuration. This is an underlying network issue (e.g., DNS failure, incorrect host) rather than a library bug, but it will manifest during connection attempts.fixVerify that the hostname or IP address specified for the remote SSH server is correct and accessible from the client's network environment. Ensure proper DNS configuration or use a direct IP address if DNS resolution is problematic.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scp'
The 'scp' library has not been installed in the current Python environment.
fixInstall the library using pip: `pip install scp`
paramiko.ssh_exception.AuthenticationException: Authentication failed.
The provided SSH credentials (username, password, or private key) are incorrect, or the user lacks necessary permissions on the remote server.
fixDouble-check the username, password, SSH key path, and ensure the remote user has appropriate permissions for the connection and target directory.
SCPException: No such file or directory
Either the specified local source file for 'put' does not exist, or the remote destination path for 'put'/'get' does not exist or is incorrect.
fixVerify that the local source file path is correct and exists, and that the remote destination directory exists before attempting the transfer.
AttributeError: 'SSHClient' object has no attribute 'open_session'
The 'SCPClient' constructor expects a 'paramiko.Transport' object, but a 'paramiko.SSHClient' object was passed directly instead.
fixPass the SSHClient's transport object to SCPClient using `ssh_client.get_transport()`. Example: `scp_client = SCPClient(ssh_client.get_transport())`
Upgrade
Version history
0.16.1latest on PyPI · released Jul 29, 2026
Audit
Dependencies
paramikorequired`scp.py` is built on top of `paramiko` for SSH transport and authentication. It is a mandatory dependency.