Automatic Docker Hosts Management

Automatically manage Docker container hostnames in your /etc/hosts file.

I built this to solve a specific problem: using Docker Compose for local development services (postgres, redis, etc.) and sharing the same compose file with CI. I wanted DATABASE_URL=postgres://postgres.localhost/mydb to work both locally and in CI without maintaining separate configs. This tool creates stable domains for Docker Compose services that work everywhere - no manual /etc/hosts edits, no environment-specific configuration. Originally extracted from my python-starter-template.

Installation

Using uv:

uv tool install docker-hosts

Using pip:

pip install docker-hosts

Usage

Update /etc/hosts with all running containers:

sudo docker-hosts

Preview what would be written without making changes:

docker-hosts --dry-run

Use a custom TLD (defaults to .localhost):

sudo docker-hosts --tld dev

Specify a custom hosts file path:

docker-hosts /tmp/hosts --dry-run

The tool requires sudo when writing to /etc/hosts, but you can test with --dry-run first to see what it would do.

Windows / WSL

When using Docker Desktop with WSL this will not work if you are not using networkingMode=mirrored.

Features

• Network-aware - picks up all network aliases from Docker networks, not just the default bridge network. If your container is attached to multiple networks, all IPs and aliases get added.
• Safe writes - uses atomic file writes (write to temp, then rename) to avoid corrupting your hosts file. Your existing entries are preserved - the tool only manages the section between ### Start Docker Domains ### and ### End Docker Domains ### markers.
• Structured logging - built with structlog for clean, parseable logs. Set LOG_LEVEL=DEBUG to see what's happening under the hood.
• Dry-run mode - test what would be written before committing to changes. Great for understanding what the tool does or debugging issues.

Development

Running Tests

Tests require Docker to be running with the postgres and redis containers from docker-compose.yml:

docker compose up -d
pytest -v

Run only unit tests (no Docker required):

pytest -v -m unit

Run only integration tests:

pytest -v -m integration

The test suite includes:

• Integration tests that verify container detection using real Docker containers
• Unit tests for data extraction and file operations
• CLI tests using temporary hosts files in tmp/hosts

MIT License