Docker.github.io: The maximum number of layers is undocumented.

[cowlinator]

Problem description

The maximum number of layers is undocumented.

Problem location

I couldn't find the information I wanted. I expected to find it near the following URL: https://docs.docker.com/engine/reference/builder/

Suggestions for a fix

The maximum number of layers that can exist in an image's history (127 layers) is not documented anywhere. This seems to be a limitation imposed by AUFS, from what I can tell.

Searching for phrases such as "max layers", "layer limit", "image depth limit", "maximum dockerfile steps", "max history length", etc. come up empty.

[bermudezmt]

@thaJeztah Sorry you're on docs speed dial, but perhaps we can look into improving the "Dockerfile Reference" page soon?

[cowlinator]

Actually, it appears that 127 is not the correct number. See https://stackoverflow.com/questions/39382518/whats-the-reason-for-the-42-layer-limit-in-docker/54936566#54936566
Is there a maximum number of layers at all? Now I'm not so sure.

[thaJeztah]

The "42 layer limit" on aufs was on older versions of aufs, but should no longer be the case.

However, the 127 layer limit is still there. This is due to a restriction of Linux not accepting more than X arguments to a syscall that's used.

Although this limit can be raised in modern kernels, it's not the default, so if we'd go beyond that maximum, an Image built on one machine may not be usable on another machine.

[thaJeztah]

Actually may not be the maximum number of arguments, but argument length (i'll have to dig it up), but yes, the limit is currently 127 layers

[nigelpoulton]

I love topics like this, but I think it's potentially one that the docs should avoid.

As mentioned above, different versions of AUFS potentially have different limits, and modern kernels may let us raise limits. This is all assuming only AUFS and not other storage drivers.

I can't personally think of a realistic way that the docs can handle a topic like this (too many variables and not viable to keep up-to-date).

I propose we close this.

[nigelpoulton]

Ping @cowlinator @thaJeztah ^^ I reckon we close this. Great discussion, but one the docs should avoid IMO.

[bermudezmt]

Thanks, @nigelpoulton . Closing as per https://github.com/docker/docker.github.io/issues/8230#issuecomment-475278273. @cowlinator please submit a new issue if you have additional concerns.