Registry / aws / alexapy

alexapy

JSON →
library1.30.0pypypi✓ verified 7d ago

AlexaPy is a Python library designed to programmatically control Amazon Echo devices. It acts as an unofficial API, primarily developed for the alexa_media_player custom component for Home Assistant. As of version 1.29.20, it provides functionalities for device interaction, login management, and sending commands to Alexa. Due to its reliance on an unofficial API, the library's functionality may change or cease without warning. The project maintains an active development status, with updates released as needed to adapt to changes in Amazon's unofficial Alexa interface.

pip install alexapy
INSTALL
IMPORT
SIG · ALEXAPY
A
alexapy
awspythonv1.30.0
Install
7.9s avg
Import
1248ms
Disk
68MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.758s · 66MB
glibc
py 3.103.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.
fix
There 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+).
fix
Monitor `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.
fix
Reduce 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.
fix
Try 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.
fix
Ensure 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.
fix
Install 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.
fix
Ensure 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.
fix
Import 'AlexaAPI' correctly: 'from alexapy.alexaapi import AlexaAPI'.
TypeError: __init__() missing 1 required positional argument: 'outputpath'
The 'AlexaLogin' class requires an 'outputpath' argument during initialization.
fix
Provide 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.
fix
Ensure 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.
Agent activity
48 hits · last 30 days
node
42
Amazon
1
Resources
alexapy — pip install alexapy · libregistry