Install & Compatibility
Where this runs
tested against v1.2.0 · 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.000s · 17.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.5s · import 0.047s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
authenticate
✓ from pamela import authenticate
open_session
✓ from pamela import open_session
close_session
✓ from pamela import close_session
check_account
✓ from pamela import check_account
change_password
✓ from pamela import change_password
PAMError
✓ from pamela import PAMError
✗ from pam import PAMError
Pamela is distinct from other `python-pam` modules, though it aims for an identical interface in some aspects.
This quickstart demonstrates how to use `pamela.authenticate` to verify a user's credentials against the system's PAM configuration. It includes error handling for `PAMError` and prompts the user for their system password using `getpass`. The default PAM service 'login' is used, and a commented-out example for a 'sudo' service is provided to illustrate flexibility.
import getpass
from pamela import authenticate, PAMError
def verify_user_pam(username, password, service='login'):
try:
# The 'login' service is a common default, but can be changed.
# On some systems, `auth` might also be a default.
# A common test is `python -m pamela -a $(whoami)`
if authenticate(username, password, service=service):
print(f"Authentication successful for user: {username}")
return True
else:
# authenticate returns False for simple failures (e.g., bad password)
# but can also raise PAMError for more critical issues.
print(f"Authentication failed for user: {username}.")
return False
except PAMError as e:
print(f"PAM error during authentication for {username}: {e}")
return False
except Exception as e:
print(f"An unexpected error occurred: {e}")
return False
if __name__ == '__main__':
user = getpass.getuser()
pwd = getpass.getpass(f"Password for {user}: ")
# Example with default 'login' service
print("\n--- Testing 'login' service ---")
verify_user_pam(user, pwd, service='login')
# Example with a custom service, e.g., 'sudo' (requires appropriate PAM setup)
# For this to work, a PAM configuration for 'sudo' might be needed, or ensure
# the user has permissions for this service.
# print("\n--- Testing 'sudo' service (if configured) ---")
# verify_user_pam(user, pwd, service='sudo')
Debug
Known issues
breakingUnlike some older Python PAM wrappers (e.g., `gnosek/python-pam`), Pamela raises a `PamError` exception for critical failures instead of simply returning `False`.fixCatch `pamela.PAMError` for robust error handling alongside checking the boolean return value of `authenticate`.
affects: All versions (since 1.0.0 merge)
gotchaPamela relies on underlying system PAM libraries (e.g., `libpam.so`, `libc.so`). It is inherently OS-specific and only functions on Unix-like operating systems (Linux, macOS POSIX). It will not work on Windows without a PAM compatibility layer.fixEnsure deployment on compatible operating systems. For cross-platform authentication, consider alternative methods or libraries not dependent on PAM.
affects: All versions
gotchaThere are reported issues with `pamela` on Python 3.14 (specifically with beta versions), where `test_environment` can fail with `PAMError: [PAM Error 26] Critical error - immediate abort`.fixAs of April 2026, it is recommended to test `pamela` thoroughly if using Python 3.14 or later. Monitor GitHub issues for updates or consider using Python 3.13 or earlier if encountering this specific error.
affects: Potentially 1.2.0 and earlier on Python 3.14+
gotchaUsing `pamela` for authentication in `sudo` or similar privileged contexts requires careful configuration of PAM service files (e.g., `/etc/pam.d/sudo`). Incorrect or insecure PAM configurations can expose the system.fixAlways follow security best practices for PAM configuration. Consult your operating system's PAM documentation when creating or modifying service files. Test privileged authentication flows thoroughly in a secure environment.
affects: All versions
Errors
Common errors & fixes
TypeError: LoadLibrary() argument 1 must be str, not None
This error typically occurs when `ctypes.util.find_library('c')` or `find_library('pam')` returns `None`, meaning the underlying C or PAM library cannot be located on the system. This is common on Windows or minimalist Linux environments.
fixPamela is designed for Unix-like systems. Ensure you are running on a compatible OS (Linux, macOS). On some minimal Linux distributions, you may need to install development packages for PAM (e.g., `libpam-dev` or `pam-devel`).
pamela.PAMError: [PAM Error 26] Critical error - immediate abort
This error has been observed in testing environments, particularly with Python 3.14 beta versions, indicating a critical PAM operation failure.
fixIf encountering this error, verify your Python version. This might be a compatibility issue with newer Python releases; consider downgrading to Python 3.13 or earlier. Check the `jupyterhub/pamela` GitHub issues for updates on Python 3.14 compatibility.
ModuleNotFoundError: No module named 'pamela'
The `pamela` package is not installed in the active Python environment or the Python interpreter cannot find it.
fixInstall the package using pip: `pip install pamela`. If using a virtual environment, ensure it's activated before installation and execution.
Authentication failed for user: <username>.
This generic message from `pamela.authenticate` usually means the provided username/password combination is incorrect for the specified PAM service, or the PAM service itself is misconfigured.
fixDouble-check the username and password. Verify that the PAM service (e.g., 'login', 'sudo') exists and is correctly configured on your system (e.g., by inspecting files in `/etc/pam.d/`). Test with a known working username/password for the target service.
Upgrade
Version history
1.2.0latest on PyPI · released Aug 9, 2024
Audit
Dependencies
No dependency data recorded yet.
Resources
No resource links recorded.