Hopsworks Python SDK

4.8.1 · active · verified Fri Apr 17

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.

Common errors

```
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='your_hopsworks_instance.com', port=443): Max retries exceeded with url: ...
```
cause The Hopsworks host URL is incorrect, inaccessible due to network issues, or a firewall is blocking the connection.

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.
```
hopsworks.rest.RestAPIError: 401 Client Error: Unauthorized for url: https://your_hopsworks_instance.com/api/project
```
cause The provided API key is incorrect, expired, or does not have sufficient permissions for the requested operation.

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.
```
hsfs.client.exceptions.FeatureStoreException: Feature group 'my_feature_group' with version 1 could not be found.
```
cause The specified feature group name or version does not exist in the connected Feature Store.

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.
```
TypeError: 'numpy.float64' object cannot be interpreted as an integer (or similar numpy type errors)
```
cause This often occurs when working with older Hopsworks SDK versions and NumPy 2.x, where internal type conversions might fail.

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`.

Warnings

breaking 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.
Fix: Upgrade `hopsworks` to version 4.6.3 or newer: `pip install --upgrade hopsworks`.
gotcha 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.
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.
gotcha 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.
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.
deprecated 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.
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.

Install

pip install hopsworks Install latest version

Imports

hopsworks
```
import hopsworks
```
hsfs
```
import hsfs
```
The `hsfs` library is the core component for interacting with the Feature Store and is often imported directly for specific classes or functions.

Quickstart

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.

import os
import hopsworks

# Configuration from environment variables for security and flexibility
HOPSWORKS_HOST = os.environ.get("HOPSWORKS_HOST", "https://your_hopsworks_instance.com")
HOPSWORKS_API_KEY = os.environ.get("HOPSWORKS_API_KEY", "")

if not HOPSWORKS_API_KEY:
    print("Warning: HOPSWORKS_API_KEY environment variable not set. Login might fail or prompt for input.")

try:
    # Connect to Hopsworks
    # If running inside a Hopsworks environment (e.g., a notebook), no arguments are typically needed.
    # For external connections, host and api_key_value are required.
    project = hopsworks.login(host=HOPSWORKS_HOST, api_key_value=HOPSWORKS_API_KEY)
    print(f"Successfully connected to Hopsworks project: {project.name}")

    # Access the Feature Store
    fs = project.get_feature_store()
    print(f"Accessed Feature Store: {fs.name}")

    # Example: Get a feature group (replace with an existing one or create a new one)
    try:
        fg = fs.get_feature_group("example_feature_group", version=1)
        print(f"Retrieved feature group: {fg.name}")
    except Exception as e:
        print(f"Could not retrieve feature group 'example_feature_group': {e}. "
              "Please ensure it exists or create one.")

except Exception as e:
    print(f"Failed to connect to Hopsworks: {e}")
    print("Please check your HOPSWORKS_HOST and HOPSWORKS_API_KEY.")

view raw JSON →