Install & Compatibility
Where this runs
tested against v1.26.9 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.758s · 66MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.9s · import 0.740s · 68MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AlexaLogin
✓ from alexapy import AlexaLogin
Main class for managing Alexa account login and sessions.
AlexaAPI
✓ from alexapy import AlexaAPI
Class for interacting with Alexa devices via the API after successful login.
WebsocketEchoClient
✓ from alexapy import WebsocketEchoClient
Class for WebSocket communication with Echo devices.
AlexapyConnectionError
✓ from alexapy.errors import AlexapyConnectionError
Exception raised for connection-related issues.
This quickstart demonstrates how to log in to an Alexa account, retrieve a list of associated devices, and send a Text-to-Speech (TTS) command to the first detected device. It uses environment variables for sensitive credentials. Replace 'your_email@example.com' and 'your_password' with actual values or set the `ALEXAPY_EMAIL` and `ALEXAPY_PASSWORD` environment variables.
import asyncio
import os
from alexapy import AlexaLogin, AlexaAPI
async def main():
email = os.environ.get('ALEXAPY_EMAIL', 'your_email@example.com')
password = os.environ.get('ALEXAPY_PASSWORD', 'your_password')
url = 'https://alexa.amazon.com'
# Initialize AlexaLogin
login = AlexaLogin(email=email, password=password, url=url)
# Attempt login
await login.login()
if await login.test_connection():
print(f"Successfully logged in to Alexa account: {email}")
# Initialize AlexaAPI with the logged-in session
alexa_api = AlexaAPI(login=login, email=email)
await alexa_api.get_devices()
if alexa_api.devices:
print("Found Alexa devices:")
for device in alexa_api.devices.values():
print(f" - {device['accountName']} (Type: {device['deviceType']})")
# Example: Send a TTS message to the first found device
first_device_id = list(alexa_api.devices.keys())[0]
await alexa_api.send_tts(first_device_id, "Hello from AlexaPy!")
print(f"Sent TTS to {alexa_api.devices[first_device_id]['accountName']}")
else:
print("No Alexa devices found.")
else:
print("Failed to log in to Alexa. Check credentials or 2FA.")
# Logout
await login.logout()
print("Logged out.")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingAlexaPy relies on an unofficial Amazon Alexa API. Amazon provides no guarantees for this API's stability, and it may change or cease functioning at any time without prior notice, potentially breaking AlexaPy functionality.fixThere is no direct fix; users must await updates to AlexaPy to adapt to Amazon's changes, or Amazon may introduce an official API.
affects: All versions
breakingDependency conflicts, particularly with `aiofiles`, can prevent `alexapy` installation or cause runtime errors. For instance, `alexapy` has historically pinned `aiofiles` to a version range (e.g., `aiofiles>=23.1.0,<24.0.0`), which can conflict with other libraries requiring `aiofiles>=24.1.0` (e.g., Home Assistant Core 2024.12.0+).fixMonitor `alexapy` releases for updated dependency requirements. If conflicts arise, consider using a isolated Python environment or waiting for `alexapy` to update its `aiofiles` dependency. For Home Assistant users, ensure your `alexa_media_player` integration is compatible with your Home Assistant Core and `alexapy` versions.
affects: 1.29.4 and later (depending on downstream requirements)
gotchaRepeated requests for voice history records using older API paths (`/alexa-privacy/apd/rvh/customer-history-records`) can lead to 'Too Many Requests' errors due to rate limiting. Amazon has a newer API path (`/alexa-privacy/apd/rvh/customer-history-records-v2`) which might offer better handling, but integration with `alexapy` requires updates.fixReduce the frequency of voice history requests. If possible, await an `alexapy` update that integrates the newer `/customer-history-records-v2` API, which might mitigate rate limit issues, though its implementation may require significant changes in `alexapy`.
affects: All versions currently using the old API path for voice history.
gotchaAuthentication issues, including 'NameError: name 'hass_url' is not defined' or persistent reauthentication requests, are common, especially when `alexapy` is used within the `alexa_media_player` Home Assistant integration. This can be due to Amazon's evolving login flow or issues with session persistence.fixTry uninstalling and reinstalling the `alexa_media_player` integration in Home Assistant. Ensure correct configuration of `hass_url` if applicable. Clear stored session data (cookies, tokens) and reauthenticate. Verify that 2FA is correctly handled, if enabled.
affects: All versions, particularly when integrated with Home Assistant.
gotchaInstallation issues such as 'Permission denied' errors, especially in containerized environments (e.g., Docker for Home Assistant), can occur when `pip` attempts to install `alexapy` into restricted directories. Missing `alexapy` directories after installation can also lead to 'module not found' errors.fixEnsure the user running `pip install` has appropriate write permissions to the installation directory. In Docker, consider using `docker exec -u <user> -it <container_name> pip install --force-reinstall alexapy` to resolve persistent installation issues or explicitly manage package directories.
affects: All versions in restrictive or containerized environments.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'alexapy'
The 'alexapy' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install alexapy'.
ImportError: cannot import name 'AlexaLogin' from 'alexapy'
The 'AlexaLogin' class is not available in the 'alexapy' module, possibly due to a version mismatch or incorrect import.
fixEnsure you are using the correct import statement: 'from alexapy.alexalogin import AlexaLogin'.
AttributeError: module 'alexapy' has no attribute 'AlexaAPI'
The 'AlexaAPI' class is not directly accessible from the 'alexapy' module.
fixImport 'AlexaAPI' correctly: 'from alexapy.alexaapi import AlexaAPI'.
TypeError: __init__() missing 1 required positional argument: 'outputpath'
The 'AlexaLogin' class requires an 'outputpath' argument during initialization.
fixProvide the 'outputpath' argument when initializing 'AlexaLogin': 'login = AlexaLogin(url, email, password, outputpath)'.
RuntimeError: Event loop is closed
Attempting to run an asynchronous function when the event loop is already closed.
fixEnsure the event loop is running before calling asynchronous functions, or use 'asyncio.run()' to manage the event loop.
Upgrade
Version history
1.30.0latest on PyPI · released Jul 22, 2026
Audit
Dependencies
aiohttprequiredAsynchronous HTTP client/server framework.
aiofilesrequiredAsynchronous file operations; specific version ranges can cause conflicts (see warnings).
pyotprequiredFor Two-Factor Authentication (2FA) support.
httpxrequiredA next generation HTTP client for Python, often used for async operations.