Install & Compatibility
Where this runs
tested against v1.2.2 · 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 · 48.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.8s · import 0.000s · 48MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Users
✓ from vonage_users import Users
✗ from vonage_users import VonageUsersClient
User
✓ from vonage_users import User
Channels
✓ from vonage_users import Channels
This quickstart demonstrates how to initialize the `VonageUsersClient`, list existing users, create a new user, retrieve a user by ID, and then delete that user for cleanup. It uses environment variables for secure API key management and includes basic error handling for Vonage API specific errors. Ensure your Vonage API keys and application ID are set as environment variables or replaced directly in the code for testing.
import vonage
import os
from vonage_users import VonageUsersClient
# Initialize Vonage client using environment variables for sensitive data
# This library requires a vonage.Client instance for its operations.
vonage_client = vonage.Client(
key=os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY'),
secret=os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET'),
private_key=os.environ.get('VONAGE_PRIVATE_KEY', 'YOUR_PRIVATE_KEY').replace('\\n', '\n'), # Handle multiline key
application_id=os.environ.get('VONAGE_APPLICATION_ID', 'YOUR_APPLICATION_ID')
)
# Initialize Vonage Users client with the base client
users_client = VonageUsersClient(vonage_client)
try:
# Example: List users
print("\n--- Listing Users ---")
users = users_client.get_users()
if users:
for user in users:
print(f"User ID: {user.id}, Name: {user.name}, Display Name: {user.display_name}")
else:
print("No users found.")
# Example: Create a user (requires appropriate permissions and valid data)
print("\n--- Creating a Test User ---")
test_user_name = "my_unique_test_user"
try:
new_user = users_client.create_user(
name=test_user_name,
display_name="My Test User",
image_url="https://example.com/default.png",
properties={"custom_tag": "dev"}
)
print(f"Successfully created user: ID={new_user.id}, Name={new_user.name}")
# Example: Get a user by ID
print(f"\n--- Retrieving User by ID: {new_user.id} ---")
retrieved_user = users_client.get_user(new_user.id)
print(f"Retrieved user: Name={retrieved_user.name}, Display Name={retrieved_user.display_name}")
# Example: Delete the created user (cleanup)
print(f"\n--- Deleting Test User: {new_user.id} ---")
users_client.delete_user(new_user.id)
print(f"User {new_user.id} deleted successfully.")
except vonage.errors.ClientError as e:
if 'name is not unique' in str(e):
print(f"Skipping user creation: User '{test_user_name}' already exists. Error: {e}")
else:
print(f"Error creating/deleting user: {e}")
except Exception as e:
print(f"An unexpected error occurred during user creation/deletion: {e}")
except vonage.errors.ClientError as e:
print(f"Vonage API Error: {e}")
print("Please ensure your VONAGE_API_KEY, VONAGE_API_SECRET, VONAGE_PRIVATE_KEY, and VONAGE_APPLICATION_ID are correctly set and have the necessary permissions.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe `vonage-users` library explicitly requires the `vonage` SDK version 3.x (e.g., `>=3.0.0,<4.0.0`). Installing an older major version of the `vonage` SDK (e.g., v2.x) will lead to dependency conflicts or runtime errors due to incompatible client interfaces.fixEnsure you have `vonage` version 3.x installed. If issues persist, try `pip install 'vonage>=3.0.0,<4.0.0' vonage-users --upgrade` or create a clean virtual environment.
affects: <1.0.0 (vonage-users) or vonage SDK <3.0.0
gotchaAuthentication for `vonage-users` is handled by an instance of the main `vonage.Client`. You must first initialize the `vonage.Client` with your API credentials (key, secret, private key, application ID) and then pass that instance to the `VonageUsersClient` constructor.fixAlways initialize `vonage_client = vonage.Client(...)` and then `users_client = VonageUsersClient(vonage_client)`.
affects: All versions
gotchaWhen creating or updating users, ensuring the `name` field is unique across all users is critical. The API will return an error if a non-unique name is provided, which can be challenging to debug without proper error handling.fixImplement robust error handling (`try...except vonage.errors.ClientError`) around user creation/update calls and consider adding a unique identifier (e.g., UUID) or timestamp to user names if conflicts are common.
affects: All versions
Upgrade
Version history
1.2.2latest on PyPI · released Apr 22, 2026
Audit
Dependencies
vonagerequiredRequired for authentication and HTTP communication with Vonage APIs.