{"id":14617,"library":"hass-nabucasa","title":"Home Assistant Nabu Casa Cloud Integration","description":"hass-nabucasa is the official Python library that powers the Nabu Casa Cloud integration within Home Assistant Core. It provides functionality for remote access, voice assistant integrations (Alexa, Google Assistant), and other cloud services for Home Assistant instances. The current version is 2.2.0, requiring Python >=3.14. Its release cadence is tightly coupled with Home Assistant Core releases, generally receiving frequent updates.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/NabuCasa/hass-nabucasa","tags":["home assistant","iot","cloud","nabu casa","voice assistant","alexa","google assistant"],"install":[{"cmd":"pip install hass-nabucasa","lang":"bash","label":"Install hass-nabucasa"}],"dependencies":[{"reason":"Core dependency; not intended for standalone use.","package":"homeassistant","optional":false},{"reason":"Cryptography backend.","package":"cffi","optional":false},{"reason":"Secure communication.","package":"cryptography","optional":false},{"reason":"Data serialization.","package":"protobuf","optional":false},{"reason":"SSL/TLS functionalities.","package":"pyopenssl","optional":false},{"reason":"HTTP client.","package":"requests","optional":false},{"reason":"Database interactions for internal state.","package":"sqlalchemy","optional":false},{"reason":"Asynchronous HTTP client.","package":"aiohttp","optional":false}],"imports":[{"note":"Primary class for Nabu Casa Cloud integration. Typically used internally by Home Assistant.","symbol":"Cloud","correct":"from hass_nabucasa import Cloud"},{"note":"Class for Alexa integration. Typically used internally by Home Assistant.","symbol":"Alexa","correct":"from hass_nabucasa import Alexa"},{"note":"Class for Google Assistant integration. Typically used internally by Home Assistant.","symbol":"GoogleAssistant","correct":"from hass_nabucasa import GoogleAssistant"}],"quickstart":{"code":"import os\nimport asyncio\nfrom unittest.mock import MagicMock\nfrom hass_nabucasa import Cloud\n\n# WARNING: This library is an internal dependency of Home Assistant Core.\n# It is NOT designed for direct standalone use by end-user applications.\n# The code below is HIGHLY conceptual and uses mocks to illustrate basic instantiation.\n# It will NOT connect to Nabu Casa Cloud or provide any meaningful functionality\n# outside of a fully operational Home Assistant environment.\n# All configuration, authentication, and service interactions are managed by Home Assistant itself.\n\nasync def main():\n    print(\"--- Conceptual hass-nabucasa usage demonstration ---\")\n    # In a real Home Assistant setup, 'hass' is the Home Assistant instance object.\n    # We're mocking it here to make the code 'runnable' without a full HA environment.\n    hass_mock = MagicMock()\n    hass_mock.config.time_zone = 'UTC'\n    hass_mock.config.latitude = 0.0\n    hass_mock.config.longitude = 0.0\n    hass_mock.config.internal_url = 'http://localhost:8123'\n    hass_mock.config.external_url = os.environ.get('HA_EXTERNAL_URL', 'http://localhost:8123')\n    hass_mock.data = {}\n    hass_mock.loop = asyncio.get_running_loop()\n    hass_mock.bus.async_listen = MagicMock()\n    hass_mock.helpers.network.get_url = MagicMock(return_value=hass_mock.config.internal_url)\n    hass_mock.helpers.aiohttp_client.async_get_clientsession = MagicMock()\n    hass_mock.components.websocket_api.async_register_command = MagicMock()\n    hass_mock.data.setdefault = MagicMock()\n\n    print(\"Attempting to instantiate hass_nabucasa.Cloud with a mocked Home Assistant instance...\")\n    try:\n        # Instantiating the Cloud class requires a 'hass' (Home Assistant) object.\n        cloud_instance = Cloud(hass_mock)\n        print(f\"Successfully created a conceptual Cloud instance: {cloud_instance}\")\n        print(\"Remember: This instance is non-functional without a full HA context.\")\n        print(\"To use Nabu Casa Cloud, configure the 'cloud:' component in Home Assistant.\")\n    except Exception as e:\n        print(f\"Failed to instantiate Cloud: {e}\")\n        print(\"This often happens if essential Home Assistant dependencies/context are missing.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how the `Cloud` class from `hass-nabucasa` is instantiated, primarily to illustrate its internal nature. **This library is an internal dependency of Home Assistant Core and is not designed for direct standalone use.** The provided code uses mocks to simulate a Home Assistant environment for basic instantiation, but it will not provide any functional cloud connectivity or services. Users interact with Nabu Casa Cloud by configuring the `cloud:` component directly within their Home Assistant `configuration.yaml` or via the UI, which then internally utilizes this library."},"warnings":[{"fix":"Interact with Nabu Casa Cloud services through Home Assistant's built-in `cloud:` integration configuration and its exposed services, rather than directly using this library.","message":"`hass-nabucasa` is an internal dependency of Home Assistant Core, not intended for direct standalone scripting by end-users. Attempting to import and use it outside a fully functional Home Assistant environment is generally unsupported and will likely lead to errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Do not manually manage `hass-nabucasa` versions. Rely on Home Assistant's dependency management, or if running in a custom environment, ensure the `hass-nabucasa` version is compatible with your `homeassistant` version.","message":"This library is tightly coupled with Home Assistant Core versions. Installing or upgrading `hass-nabucasa` independently of `homeassistant` can introduce breaking changes, compatibility issues, or lead to a non-functional cloud integration. Always ensure `hass-nabucasa` matches the expected version for your Home Assistant release, which typically means letting Home Assistant manage its dependencies.","severity":"breaking","affected_versions":"All versions, especially across major Home Assistant releases"},{"fix":"Manage Nabu Casa Cloud settings and linked voice assistants through the Home Assistant UI or `configuration.yaml` file, not through direct interaction with this library's code.","message":"All configuration, including Nabu Casa Cloud subscription management and authentication for integrations like Alexa or Google Assistant, is handled entirely within Home Assistant's `cloud:` configuration. Direct programmatic access to cloud credentials or services via `hass-nabucasa`'s API is not exposed for external use.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[],"ecosystem":"pypi"}