Python Hosts File Manager

Common errors

• PermissionError: [Errno 13] Permission denied: '/etc/hosts' (or Windows equivalent)

  cause The script attempted to write to the system hosts file without sufficient administrative/root privileges.
  fix Run 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')

  cause Incorrect import statement. The main classes (`Hosts`, `HostsEntry`) are part of the `python_hosts` package, not a module named `hosts`.
  fix Change the import statement to `from python_hosts import Hosts, HostsEntry`.

• Changes not reflected in hosts file after running script

  cause The `.write()` method was not called on the `Hosts` object after modifications, so changes were not saved to disk.
  fix Ensure `my_hosts.write()` is called after all desired additions, removals, or other modifications to the `Hosts` object.

Warnings

• gotcha Changes 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.
  Fix: Always call `hosts_instance.write()` after making any modifications (add, remove, etc.) to ensure changes are saved to the hosts file.
• gotcha When 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.
  Fix: For 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.
• gotcha While `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.
  Fix: Develop 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.

Install

• pip install python-hosts Install with pip

Imports

• Hosts
  wrong:

  import Hosts

  correct:

  from python_hosts import Hosts

  The `Hosts` class is nested within the `python_hosts` package.
• HostsEntry
  wrong:

  from python_hosts.hosts import HostsEntry

  correct:

  from python_hosts import HostsEntry

  `HostsEntry` is directly available from the top-level `python_hosts` package, not a submodule.

Quickstart

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)