{"id":9815,"library":"hopsworks","title":"Hopsworks Python SDK","description":"The Hopsworks Python SDK provides a client library to interact with the Hopsworks Platform, including its Feature Store, Model Registry, and Model Serving capabilities. It allows data scientists and ML engineers to programmatically manage ML artifacts and data. The library is actively maintained, with frequent minor releases (often monthly or bi-monthly) to introduce new features and improvements. The current version is 4.8.1.","status":"active","version":"4.8.1","language":"en","source_language":"en","source_url":"https://github.com/logicalclocks/hopsworks-api","tags":["machine learning","feature store","mlops","data science","hoplite"],"install":[{"cmd":"pip install hopsworks","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version range","package":"python","optional":false},{"reason":"Compatibility with numpy 1.x and 2.x was addressed in 4.6.3; older versions might have issues.","package":"numpy","optional":false}],"imports":[{"symbol":"hopsworks","correct":"import hopsworks"},{"note":"The `hsfs` library is the core component for interacting with the Feature Store and is often imported directly for specific classes or functions.","symbol":"hsfs","correct":"import hsfs"}],"quickstart":{"code":"import os\nimport hopsworks\n\n# Configuration from environment variables for security and flexibility\nHOPSWORKS_HOST = os.environ.get(\"HOPSWORKS_HOST\", \"https://your_hopsworks_instance.com\")\nHOPSWORKS_API_KEY = os.environ.get(\"HOPSWORKS_API_KEY\", \"\")\n\nif not HOPSWORKS_API_KEY:\n    print(\"Warning: HOPSWORKS_API_KEY environment variable not set. Login might fail or prompt for input.\")\n\ntry:\n    # Connect to Hopsworks\n    # If running inside a Hopsworks environment (e.g., a notebook), no arguments are typically needed.\n    # For external connections, host and api_key_value are required.\n    project = hopsworks.login(host=HOPSWORKS_HOST, api_key_value=HOPSWORKS_API_KEY)\n    print(f\"Successfully connected to Hopsworks project: {project.name}\")\n\n    # Access the Feature Store\n    fs = project.get_feature_store()\n    print(f\"Accessed Feature Store: {fs.name}\")\n\n    # Example: Get a feature group (replace with an existing one or create a new one)\n    try:\n        fg = fs.get_feature_group(\"example_feature_group\", version=1)\n        print(f\"Retrieved feature group: {fg.name}\")\n    except Exception as e:\n        print(f\"Could not retrieve feature group 'example_feature_group': {e}. \"\n              \"Please ensure it exists or create one.\")\n\nexcept Exception as e:\n    print(f\"Failed to connect to Hopsworks: {e}\")\n    print(\"Please check your HOPSWORKS_HOST and HOPSWORKS_API_KEY.\")","lang":"python","description":"This quickstart demonstrates how to connect to a Hopsworks instance, retrieve a project, and access its Feature Store using environment variables for sensitive credentials. It includes error handling for common connection issues and accessing a non-existent feature group."},"warnings":[{"fix":"Upgrade `hopsworks` to version 4.6.3 or newer: `pip install --upgrade hopsworks`.","message":"The Hopsworks SDK versions prior to 4.6.3 might experience compatibility issues with NumPy 2.x. If you're using NumPy 2.x, ensure your `hopsworks` library is at least 4.6.3.","severity":"breaking","affected_versions":"<4.6.3"},{"fix":"Verify that `HOPSWORKS_HOST` points to your Hopsworks instance URL (e.g., `https://my.hopsworks.ai`) and `HOPSWORKS_API_KEY` contains the correct API key. Ensure no leading/trailing spaces or incorrect characters. When running inside a Hopsworks environment (e.g., a Jupyter notebook on the platform), `login()` without arguments is usually sufficient.","message":"Incorrect `host` or `api_key_value` in `hopsworks.login()` is a common cause of connection failures. The `api_key_value` must be a valid API key generated from the Hopsworks UI for your user.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the official documentation for schema validation guidelines when writing to feature groups. Upgrade to `hopsworks` 4.7.0 or newer to benefit from improved online schema validation and handling of malformed tags. Ensure your DataFrame schema precisely matches the target feature group schema.","message":"Schema validation behavior for writing to feature groups, especially Delta Feature Groups, was improved in version 4.7.0. Older versions or specific configurations might lead to unexpected behavior or `FeatureStoreException`s if schemas are not strictly aligned.","severity":"gotcha","affected_versions":"<4.7.0"},{"fix":"Adhere to the high-level `hopsworks` API for platform interactions and `hsfs` for feature store operations. Consult the latest official documentation for recommended patterns for job orchestration and model deployment.","message":"Direct instantiation or extensive use of internal `hoplite` components (e.g., for job orchestration) might be discouraged or change in future releases. The public API primarily focuses on `hopsworks.login()` and project/feature store methods.","severity":"deprecated","affected_versions":"Potentially 4.x, specific minor versions not clearly documented for deprecation"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Double-check the `HOPSWORKS_HOST` value. Ensure your machine has network access to the Hopsworks instance (e.g., VPN, correct DNS). Verify proxy settings if applicable.","cause":"The Hopsworks host URL is incorrect, inaccessible due to network issues, or a firewall is blocking the connection.","error":"requests.exceptions.ConnectionError: HTTPSConnectionPool(host='your_hopsworks_instance.com', port=443): Max retries exceeded with url: ..."},{"fix":"Generate a new API key in the Hopsworks UI and ensure it is correctly passed as `api_key_value` to `hopsworks.login()`. Check the project's permissions for the API key.","cause":"The provided API key is incorrect, expired, or does not have sufficient permissions for the requested operation.","error":"hopsworks.rest.RestAPIError: 401 Client Error: Unauthorized for url: https://your_hopsworks_instance.com/api/project"},{"fix":"Verify the feature group name and version. You can list existing feature groups using `fs.get_feature_groups()` or `fs.get_or_create_feature_group(...)` if you intend to create it.","cause":"The specified feature group name or version does not exist in the connected Feature Store.","error":"hsfs.client.exceptions.FeatureStoreException: Feature group 'my_feature_group' with version 1 could not be found."},{"fix":"Upgrade your `hopsworks` library to version 4.6.3 or newer to ensure compatibility with both NumPy 1.x and 2.x: `pip install --upgrade hopsworks`.","cause":"This often occurs when working with older Hopsworks SDK versions and NumPy 2.x, where internal type conversions might fail.","error":"TypeError: 'numpy.float64' object cannot be interpreted as an integer (or similar numpy type errors)"}]}