A modern, type-safe Python library for Hetzner Cloud Server management with comprehensive API coverage.
- Complete Server Lifecycle Management - Create, manage, and delete cloud servers
- All Server Actions - Power management, backups, rescue mode, ISO handling, and more
- Type Safety - Full type hints throughout the codebase
- Dry-Run Mode - Test your code without making real API calls
- Comprehensive Error Handling - Detailed exception hierarchy
- Automatic Model Parsing - JSON responses automatically converted to Python objects
- Rate Limiting Aware - Built-in handling of API rate limits
- Modern Python - Supports Python 3.8+
pip install pyhetznerserverFirst, create an API token in the Hetzner Cloud Console:
- Go to your project
- Navigate to Security → API Tokens
- Generate a new token with appropriate permissions
from pyhetznerserver import HetznerClient
# Initialize client
client = HetznerClient(token="your_api_token_here")
# List all servers
servers = client.servers.list()
print(f"Found {len(servers)} servers")
# Create a new server
server, action = client.servers.create(
name="my-web-server",
server_type="cx11",
image="ubuntu-20.04",
location="fsn1",
ssh_keys=["your-ssh-key-name"],
labels={"env": "production", "app": "web"}
)
print(f"Server created: {server.name} ({server.public_net.ipv4.ip})")
# Server management
server.power_off() # Power off server
server.power_on() # Power on server
server.reboot() # Reboot server
server.reset() # Hard reset
# Advanced operations
server.enable_backup("22-02") # Enable daily backups
server.create_image("my-snapshot") # Create server image
server.enable_rescue() # Enable rescue mode
server.attach_iso("ubuntu-20.04") # Mount ISO
server.change_type("cx21", upgrade_disk=True) # Upgrade server
# Cleanup
client.close()server.power_on() # Start server
server.power_off() # Stop server
server.reboot() # Restart server
server.reset() # Force restart
server.shutdown() # Graceful shutdownserver.enable_backup("22-02") # Enable backups at 22:00-02:00 UTC
server.disable_backup() # Disable backups
server.create_image("snapshot-name") # Create snapshot
server.rebuild("ubuntu-22.04") # Rebuild from imagepassword, action = server.enable_rescue("linux64", ssh_keys=["key1"])
server.disable_rescue()
server.attach_iso("ubuntu-20.04")
server.detach_iso()server.attach_to_network(network_id, ip="10.0.0.100")
server.detach_from_network(network_id)
server.change_dns_ptr("1.2.3.4", "server.example.com")password, action = server.reset_password()
server.change_protection(delete=True, rebuild=False)Access comprehensive server information through nested objects:
server = client.servers.get(server_id)
# Basic info
print(f"Server: {server.name} (ID: {server.id})")
print(f"Status: {server.status}")
print(f"Created: {server.created}")
# Network information
print(f"IPv4: {server.public_net.ipv4.ip}")
print(f"IPv6: {server.public_net.ipv6.ip}")
# Hardware details
print(f"Type: {server.server_type.name}")
print(f"CPU Cores: {server.server_type.cores}")
print(f"RAM: {server.server_type.memory} GB")
print(f"Disk: {server.server_type.disk} GB")
# Location
print(f"Datacenter: {server.datacenter.name}")
print(f"Location: {server.datacenter.location.city}, {server.datacenter.location.country}")
# Operating System
print(f"OS: {server.image.name} ({server.image.os_flavor})")Enable dry-run mode for testing without making real API calls:
client = HetznerClient(token="fake_token", dry_run=True)
# All operations return mock data
servers = client.servers.list() # Returns empty list
server, action = client.servers.create(name="test", server_type="cx11", image="ubuntu-20.04")
print(f"Mock server created: {server.name}") # Uses fake dataThe library provides detailed exception hierarchy:
from pyhetznerserver import (
HetznerAPIError,
AuthenticationError,
ValidationError,
ServerNotFoundError,
RateLimitError
)
try:
server = client.servers.get(999999)
except ServerNotFoundError:
print("Server not found")
except AuthenticationError:
print("Invalid API token")
except RateLimitError:
print("API rate limit exceeded")
except ValidationError as e:
print(f"Invalid input: {e}")
except HetznerAPIError as e:
print(f"API error: {e}")# Filter servers
servers = client.servers.list(
status="running",
label_selector="env=production",
sort="name:asc"
)
# Pagination
servers = client.servers.list(page=2, per_page=10)# Create server with labels
server, action = client.servers.create(
name="web-server",
server_type="cx11",
image="ubuntu-20.04",
labels={
"environment": "production",
"team": "backend",
"cost-center": "engineering"
}
)
# Filter by labels
prod_servers = client.servers.list(label_selector="environment=production")client = HetznerClient(
token="your_token",
dry_run=False, # Enable for testing
timeout=30 # Request timeout in seconds
)This library covers all Hetzner Cloud Server API endpoints:
- ✅ Server Management - CRUD operations
- ✅ Power Actions - Start, stop, reboot, reset
- ✅ Image Management - Create snapshots, rebuild
- ✅ Backup System - Enable/disable, scheduling
- ✅ Rescue Mode - Recovery operations
- ✅ ISO Handling - Mount/unmount ISO images
- ✅ Network Operations - Attach/detach networks
- ✅ DNS Management - PTR record management
- ✅ Security - Password reset, protection settings
- ✅ Server Types - Hardware configuration changes
- ✅ Actions - Retrieve operation status and history
Contributions are welcome! Please read our Contributing Guide for details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Hetzner Cloud for providing excellent cloud infrastructure
- The Python community for amazing tools and libraries
- 📖 Documentation: GitHub Repository
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- hcloud-python - Official Hetzner Cloud Python library
- terraform-provider-hcloud - Terraform provider
Made with ❤️ for the Python and Hetzner Cloud community