10.1.1.3 Registry Layer Upload
A focused guide to Registry Layer Upload, connecting core concepts with practical Docker and container operations.
Registry layer upload is the actual mechanism by which docker push transfers an image's content to a registry, operating at the level of individual layers rather than treating the image as one indivisible blob, allowing only genuinely new content to be transferred.
How Push Breaks an Image Into Layer Uploads
Pushing an image involves uploading each of its constituent layers individually, with the registry tracking which layers it already has.
docker push registry.example.com/myteam/myapi:2.3.0
a1b2c3d4e5f6: Pushed
f6e5d4c3b2a1: Layer already exists
9876543210ab: Pushed
This output reveals that one layer was already present in the registry, requiring no actual upload, while the other two genuinely needed to be transferred.
Why This Layer-By-Layer Approach Is Efficient
Two different images sharing a common base often share several of their underlying layers — once one of those images has been pushed, pushing the other only requires uploading the layers genuinely unique to it.
docker push registry.example.com/myteam/myapi:2.4.0
If 2.4.0 differs from an already-pushed 2.3.0 only in its final application layer, this push completes quickly, since only that one new layer actually needs uploading.
Monitoring Upload Progress for Larger Images
For an image with substantial content in layers that do need uploading, the push output shows progress for each layer being transferred.
docker push myapi:2.3.0
a1b2c3d4e5f6: Pushing [==========> ] 45MB/89MB
Why Registry Layer Upload Matters
This granular, layer-aware upload mechanism is what makes pushing successive versions of a frequently updated image practical, avoiding the need to fully re-upload an image's entire content just because one small part of it changed.