Install & Compatibility
Where this runs
tested against v1.1.2 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.089s · 19.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.085s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Hosts
✓ from python_hosts import Hosts
✗ import Hosts
The `Hosts` class is nested within the `python_hosts` package.
HostsEntry
✓ from python_hosts import HostsEntry
✗ from python_hosts.hosts import HostsEntry
`HostsEntry` is directly available from the top-level `python_hosts` package, not a submodule.
This quickstart demonstrates how to initialize a `Hosts` object, add new entries using `HostsEntry`, and persist changes to a specified hosts file. For safety, it uses a temporary test file instead of the system's default hosts file. It also shows how to merge additional hostnames to an existing IP address entry.
from python_hosts import Hosts, HostsEntry
import os
# Create a Hosts instance, using a test file to avoid modifying the system hosts file directly
hosts_file_path = os.path.join(os.getcwd(), 'hosts_test')
my_hosts = Hosts(path=hosts_file_path)
# Add a new entry
new_entry = HostsEntry(entry_type='ipv4', address='127.0.0.1', names=['localhost.dev', 'myapp.local'])
my_hosts.add([new_entry])
# Add another entry, demonstrating merging names
additional_entry = HostsEntry(entry_type='ipv4', address='192.168.1.100', names=['backend.api'])
my_hosts.add([additional_entry])
# Merge names to an existing entry
merge_entry = HostsEntry(entry_type='ipv4', address='127.0.0.1', names=['dev.server'])
my_hosts.add([merge_entry], merge_names=True)
# Write changes back to the file
my_hosts.write()
print(f"Hosts file updated at: {hosts_file_path}")
# Verify content (optional)
with open(hosts_file_path, 'r') as f:
print("\n--- Current hosts_test content ---")
print(f.read())
# Clean up the test file
os.remove(hosts_file_path)
Debug
Known issues
gotchaChanges made via `python-hosts` are not persisted until the `.write()` method is explicitly called on the `Hosts` object. Failing to call `.write()` will result in all modifications being lost.fixAlways call `hosts_instance.write()` after making any modifications (add, remove, etc.) to ensure changes are saved to the hosts file.
affects: All versions
gotchaWhen initializing `Hosts()`, if `path` is not provided, the library attempts to determine the default hosts file path for the current operating system (e.g., `/etc/hosts` on Linux, `C:\Windows\System32\drivers\etc\hosts` on Windows). Directly modifying this file often requires elevated permissions (root/administrator), which can lead to `PermissionError` or `FileNotFoundError` if the script lacks the necessary privileges.fixFor testing or non-privileged operations, specify a `path` to a temporary or user-owned file (e.g., `Hosts(path='my_test_hosts')`). For production use cases modifying the system hosts file, ensure your script runs with appropriate elevated permissions.
affects: All versions
gotchaWhile `python-hosts` supports Python 2.7, new development should prioritize Python 3.x to leverage modern language features and benefit from continued community support and security updates. Relying on Python 2.7 for new projects is generally discouraged.fixDevelop new projects targeting Python 3.5+ or newer. If maintaining legacy Python 2.7 code, be aware of the end-of-life status for Python 2 itself.
affects: Compatibility across 2.7 and 3.5+
Errors
Common errors & fixes
PermissionError: [Errno 13] Permission denied: '/etc/hosts' (or Windows equivalent)
The script attempted to write to the system hosts file without sufficient administrative/root privileges.
fixRun the Python script with elevated permissions (e.g., `sudo python your_script.py` on Linux/macOS, or 'Run as administrator' on Windows). Alternatively, specify a `path` to a user-writable file for development or testing: `my_hosts = Hosts(path='my_custom_hosts_file.txt')`.
ImportError: cannot import name 'Hosts' from 'hosts' (or similar 'ModuleNotFoundError: No module named 'hosts')
Incorrect import statement. The main classes (`Hosts`, `HostsEntry`) are part of the `python_hosts` package, not a module named `hosts`.
fixChange the import statement to `from python_hosts import Hosts, HostsEntry`.
Changes not reflected in hosts file after running script
The `.write()` method was not called on the `Hosts` object after modifications, so changes were not saved to disk.
fixEnsure `my_hosts.write()` is called after all desired additions, removals, or other modifications to the `Hosts` object.
Upgrade
Version history
1.1.2latest on PyPI · released Jun 24, 2025
Audit
Dependencies
No dependency data recorded yet.