Hetzner Cloud Python Library

Common errors

• hcloud: unable to authenticate your token (unauthorized)

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

• KeyError: 'HCLOUD_TOKEN'

  cause The `HCLOUD_TOKEN` environment variable, which the `hcloud` client expects by default for authentication, has not been set in the execution environment.
  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).

• SyntaxError: invalid non-printable character U+00A0

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

Warnings

• breaking 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.
  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', ...)`.
• gotcha 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.
  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.
• deprecated 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`.
  Fix: Consult the library's changelog and docstrings. Update your code to use the recommended alternative method as indicated by `DeprecationWarning` messages or documentation.

Install

• pip install hcloud Install stable release

Imports

• Client

  from hcloud import Client

Quickstart

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.

import os
from hcloud import Client

HCLOUD_TOKEN = os.environ.get('HCLOUD_TOKEN', '')

if not HCLOUD_TOKEN:
    print("Error: HCLOUD_TOKEN environment variable not set.")
    exit(1)

client = Client(token=HCLOUD_TOKEN, application_name="my-app", application_version="1.0.0")

# Example: List all servers
try:
    servers = client.servers.get_all()
    if servers:
        print("Hetzner Cloud Servers:")
        for server in servers:
            print(f"  - ID: {server.id}, Name: {server.name}, Status: {server.status}")
    else:
        print("No servers found.")
except Exception as e:
    print(f"An error occurred: {e}")