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.
Using uv:
uv tool install docker-hostsUsing pip:
pip install docker-hostsUpdate /etc/hosts with all running containers:
sudo docker-hostsPreview what would be written without making changes:
docker-hosts --dry-runUse a custom TLD (defaults to .localhost):
sudo docker-hosts --tld devSpecify a custom hosts file path:
docker-hosts /tmp/hosts --dry-runFilter containers by their Docker names using repeatable regular expressions:
sudo docker-hosts --include '^myproject-' --exclude 'worker'Update the hosts file and output the resulting aliases as JSON:
sudo docker-hosts --include '^myproject-' --jsonCombine --json with --dry-run to output JSON without modifying the hosts file.
Logs default to stderr so stdout can be safely piped to another command. Set
PYTHON_LOG_PATH to override the log destination.
When both options are provided, a container must match at least one --include
expression and no --exclude expressions. Without filters, all running containers
are included.
If multiple running containers claim the same hostname, the ambiguous hostname is
omitted from all generated entries and a warning identifies the affected containers.
Collisions are detected across all running containers before --include and
--exclude determine which containers are written or reported. Warnings are only
emitted when a collision affects selected containers, but list all claimants.
The tool requires permission to replace the hosts file and will suggest using
sudo or --dry-run when permission is denied. You can test with --dry-run
first to see what it would do.
You may encounter issues if using Docker Desktop. Running Docker directly on WSL works properly.
- 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=DEBUGto 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.
Tests require Docker to be running with the postgres and redis containers from docker-compose.yml:
docker compose up -d
pytest -vRun only unit tests (no Docker required):
pytest -v -m unitRun only integration tests:
pytest -v -m integrationThe 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
Run just install_editable to install this checkout globally in editable mode. Source changes are reflected without reinstalling.
This requires uv, just, zsh, and jq. If mise is available, the recipe also updates every installed pipx:docker-hosts environment so mise can use the local checkout. Re-run after mise upgrades, which replace those editable installations.
This project was created from iloveitaly/python-package-template