{"id":8214,"library":"hcloud","title":"Hetzner Cloud Python Library","description":"The `hcloud` library is the official Python client for interacting with the Hetzner Cloud API, enabling programmatic management of resources such as servers, networks, volumes, and more. It is actively maintained with frequent releases, currently at version 2.17.1, providing access to the latest Hetzner Cloud features and API updates.","status":"active","version":"2.17.1","language":"en","source_language":"en","source_url":"https://github.com/hetznercloud/hcloud-python","tags":["cloud","hetzner","hcloud","api","infrastructure","server","storage","network","automation"],"install":[{"cmd":"pip install hcloud","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"Client","correct":"from hcloud import Client"}],"quickstart":{"code":"import os\nfrom hcloud import Client\n\nHCLOUD_TOKEN = os.environ.get('HCLOUD_TOKEN', '')\n\nif not HCLOUD_TOKEN:\n    print(\"Error: HCLOUD_TOKEN environment variable not set.\")\n    exit(1)\n\nclient = Client(token=HCLOUD_TOKEN, application_name=\"my-app\", application_version=\"1.0.0\")\n\n# Example: List all servers\ntry:\n    servers = client.servers.get_all()\n    if servers:\n        print(\"Hetzner Cloud Servers:\")\n        for server in servers:\n            print(f\"  - ID: {server.id}, Name: {server.name}, Status: {server.status}\")\n    else:\n        print(\"No servers found.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"Initializes the Hetzner Cloud client using an API token from the `HCLOUD_TOKEN` environment variable and lists all available servers. This demonstrates basic client setup and interaction with resources."},"warnings":[{"fix":"Migrate your code to use `location` instead of `datacenter` when creating or managing Servers and Primary IPs. For example, `client.servers.create(location='fsn1', ...)` instead of `client.servers.create(datacenter='fsn1-dc14', ...)`.","message":"The `datacenter` property in `Servers` and `Primary IPs` objects and API requests is deprecated and will be removed after July 1, 2026. Use the `location` property instead.","severity":"breaking","affected_versions":">=2.13.0"},{"fix":"Always check release notes and the `hcloud` documentation for new features. If using experimental features, pin to exact minor versions or be prepared for breaking changes until the feature is generally available.","message":"New features or API endpoints may be introduced as 'experimental'. During an experimental phase, breaking changes to these features may occur in minor releases. Check the release notes and docstrings for 'Experimental' notices.","severity":"gotcha","affected_versions":"All versions with experimental features (e.g., Storage Boxes in v2.12.0)"},{"fix":"Consult the library's changelog and docstrings. Update your code to use the recommended alternative method as indicated by `DeprecationWarning` messages or documentation.","message":"Specific methods may be deprecated in favor of more robust or precise alternatives. For instance, `hcloud.images.client.ImagesClient.get_by_name` was deprecated in favor of `get_by_name_and_architecture`.","severity":"deprecated","affected_versions":"Specific versions as noted in release changelogs and docstrings (e.g., Image methods in v1.19+ of underlying API)."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the `HCLOUD_TOKEN` environment variable contains the *full* 64-character API token generated from the Hetzner Cloud console. Generate a new token if unsure.","cause":"The provided Hetzner Cloud API token is incorrect, expired, or has insufficient permissions. A common mistake is using a truncated token (only the prefix) displayed in the console instead of the full 64-character token generated upon creation.","error":"hcloud: unable to authenticate your token (unauthorized)"},{"fix":"Set the `HCLOUD_TOKEN` environment variable before running your Python script. Example: `export HCLOUD_TOKEN='your_api_token'` (Linux/macOS) or `$env:HCLOUD_TOKEN='your_api_token'` (PowerShell).","cause":"The `HCLOUD_TOKEN` environment variable, which the `hcloud` client expects by default for authentication, has not been set in the execution environment.","error":"KeyError: 'HCLOUD_TOKEN'"},{"fix":"Carefully retype the problematic line of code, especially where API tokens or other string literals are defined, or use an editor with whitespace visualization to remove any hidden characters. Ensure your file encoding is UTF-8.","cause":"This error typically occurs when code, especially API keys or configuration strings, is copy-pasted from a web page or document that includes hidden Unicode characters (like a non-breaking space U+00A0) that Python's parser cannot handle.","error":"SyntaxError: invalid non-printable character U+00A0"}]}