hcloud

library2.21.0pypypi✓ verified 85d ago

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.

aws http-networking

pip install hcloud

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · HCLOUD

hcloud

awspythonv2.21.0

Install

2.3s avg

Import

678ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.21.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.707s · 23.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.3s · import 0.650s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from hcloud import Client

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}")

hcloud --version

Debug

Known issues

breakingThe `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', ...)`.

affects: >=2.13.0

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

affects: All versions with experimental features (e.g., Storage Boxes in v2.12.0)

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

affects: Specific versions as noted in release changelogs and docstrings (e.g., Image methods in v1.19+ of underlying API).

Errors

Common errors & fixes

hcloud: unable to authenticate your token (unauthorized)

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'

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

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.

Upgrade

Version history

2.21.0latest on PyPI · released Jun 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

Resources

githubhttps://github.com/hetznercloud/hcloud-python ↗

packagehttps://pypi.org/project/hcloud/ ↗

homepagehttps://www.hetzner.com/cloud ↗

docshttps://hcloud-python.readthedocs.io/en/stable/ ↗

changeloghttps://github.com/hetznercloud/hcloud-python/blob/main/CHANGELOG.md ↗