Skip to content
Blog

Insecure Registries: When and How to Use Them (Development Only)

Understanding Docker insecure-registries settings, configuring daemon.json for local HTTP test environments, risks of plain-text credentials, and why to avoid it in production.

Published on • November 18, 2026

AI Assistant

By default, the Docker Engine CLI enforces encrypted HTTPS/TLS connections for all container registry interactions. If you try to push or pull an image from an unencrypted HTTP registry (e.g., 192.168.1.50:5000), Docker aborts the request to protect your data.

While HTTPS is mandatory for production, developers setting up short-lived local test registries, air-gapped laboratory subnets, or CI integration tests sometimes need to bypass TLS checks using the insecure-registries daemon setting.

In this article, we will cover how insecure-registries works, how to configure it on Linux, macOS, and Windows, the severe security risks involved, and why it must never be used in production.

Why Docker Blocks Insecure Registries

When Docker communicates with an insecure HTTP registry, two critical vulnerabilities are exposed:

+-----------------------------------------------------------------------------------+
| Security Risks of Insecure HTTP Registries                                       |
+-----------------------------------------------------------------------------------+
| 1. Credential Exposure in Cleartext                                               |
|    - HTTP Basic authentication headers (`Authorization: Basic ...`) are transmitted|
|      in plain unencrypted text across the network.                                |
| 2. Man-in-the-Middle (MitM) Image Tampering                                       |
|    - Malicious actors on the local network can intercept image downloads and       |
|      inject backdoor binaries into container layers without detection.             |
+-----------------------------------------------------------------------------------+

Docker exceptions: Connections to localhost or 127.0.0.1 are automatically treated as secure by Docker, so docker push localhost:5000/app:v1 works without configuring insecure-registries.

Valid Development Use Cases

Configuring an insecure registry is acceptable only under these strict isolated conditions:

  • Local VM or Minikube Testing: Communicating with a test registry running on a local VM IP (e.g. 192.168.99.100:5000).
  • Temporary CI/CD Integration Testing: Disposable ephemerally isolated build runners inside a private VPC.
  • Proof-of-Concept Proofing: Validating registry setup steps before issuing TLS certificates.

How to Configure insecure-registries

To instruct the Docker Engine daemon to allow unencrypted HTTP connections to a specific registry, edit the Docker daemon configuration file (daemon.json).

1. Linux Setup (/etc/docker/daemon.json)

Edit or create /etc/docker/daemon.json:

{
  "insecure-registries": [
    "192.168.1.50:5000",
    "my-test-registry.local:5000"
  ]
}

Apply the changes by restarting the Docker daemon service:

sudo systemctl restart docker

Verify that the setting was loaded successfully:

docker info | grep -A 5 "Insecure Registries"

Sample output:

 Insecure Registries:
  192.168.1.50:5000
  my-test-registry.local:5000
  127.0.0.0/8

2. Docker Desktop Setup (macOS & Windows)

  1. Open Docker Desktop Settings.
  2. Select Docker Engine from the left navigation menu.
  3. Add the "insecure-registries" array to the JSON configuration pane.
  4. Click Apply & restart.
{
  "builder": { "gc": { "defaultKeepStorage": "20GB", "enabled": true } },
  "experimental": false,
  "insecure-registries": [
    "10.0.0.45:5000"
  ]
}

Why Insecure Registries are Forbidden in Production

Security MetricSecure Registry (HTTPS/TLS)Insecure Registry (HTTP)
Data Encryption256-bit TLS EncryptionPlaintext (Unencrypted)
Identity VerificationAuthenticated via Trust Chain / CAZero identity verification
Credential SafetyProtectedEasily sniffed via Wireshark / tcpdump
MitM ProtectionProtectedCompletely vulnerable
Compliance (SOC2 / PCI)CompliantFails compliance audits immediately

Safer Alternatives for Local Development

Instead of bypassing security with insecure-registries:

  1. Use localhost Forwarding: Use SSH tunnels or port forwarding so the registry is reached via localhost:5000 (which Docker trusts natively).
  2. Use Free Self-Signed CA Certs: Generate a local self-signed CA and place the root certificate in /etc/docker/certs.d/ as shown in our TLS guide.
  3. Use mkcert for Local Domain Certs: Tools like mkcert generate locally trusted development certificates in seconds without disabling TLS validation.

Summary

The insecure-registries directive is a developer convenience intended exclusively for isolated testing. Never enable insecure registries on production nodes or corporate build networks.