[Bug]: proot-distro kept saying "Failed to install: Unauthorized"

[LCSOGthb]

Problem description

Recently proot-distro on my termux kept reporting

[!] Failed to install: Unauthorized: 'docker.io/library/ubuntu:24.04' does not exist or is a private image. Set PD_DOCKER_AUTH=username:password to authenticate.
[!] See 'proot-distro install --help' on how to install distribution image.

While using curl shows my phone can access to docker's registry and auth endpoint normally

~ $ curl -I https://registry-1.docker.io/v2/
HTTP/2 401
date: Sun, 28 Jun 2026 02:48:22 GMT
content-type: application/json
content-length: 87
docker-distribution-api-version: registry/2.0
www-authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io"
strict-transport-security: max-age=31536000

~ $ curl -I "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/ubuntu:pull"
HTTP/2 405
date: Sun, 28 Jun 2026 02:48:47 GMT
allow: GET
allow: POST
x-trace-id: 0e6cd68012ccf7a912e7d737ba082ccb
x-trace-sampled: true
strict-transport-security: max-age=31536000
cf-cache-status: DYNAMIC
set-cookie: __cf_bm=MU_S7rJgFiuss9GOa7.lJacr1YJipZbcHwu9QGr2Sds-1782614927.0632575-1.0.1.1-KG5BMdVZHe5UJi61YCNobuZwycGQF8vQ2WABVx4KE4nkhJTYh7Hjo0OFwIsB5.RvHRtsQrXyJdcfEdQwFvdeaPZfqptpxhfyi9fWOeVyfCo1wmVwRFtYPBcg2md1u1Om; HttpOnly; SameSite=None; Secure; Path=/; Domain=auth.docker.io; Expires=Sun, 28 Jun 2026 03:18:47 GMT
server: cloudflare
cf-ray: a1295fde29cdb4d6-KUL

Tried proot-distro install alpine:latest, proot-distro install docker.io/library/ubuntu:24.04, proot-distro install ubuntu. Nothing change.

What steps will reproduce the bug?

1. proot-distro install docker.io/library/ubuntu:24.04 or proot-distro install alpine:latest or proot-distro install ubuntu

What is the expected behavior?

No response

[LCSOGthb]

proot-distro works when using ghcr.io as installation source (proot-distro install ghcr.io/homebrew/ubuntu22.04:latest) instead of docker

[LCSOGthb]

Update:
[] 4f4fb700ef54: Applying layer 4/7...
[] 5bd01cc8533a: Downloading layer 5/7 (1.2 GiB)...
[!] Failed to install: Layer integrity check failed for digest 'sha256:5bd01cc8533a4b8dd5c192c530094a98d00485cab2eaef137eace98a535d8dcd': expected 5bd01cc8533a4b8dd5c192c530094a98d00485cab2eaef137eace98a535d8dcd, got 2f9bb41ff52568f9666f4225367ca240ca2de0ea10693520ba0941a7da81b8dc.
[!] See 'proot-distro install --help' on how to install distribution image.

[sylirre]

docker.io has per-IP pull limits for anonymous/free users. Don't report this as issue of proot-distro. I won't fix that or change default registry.

Free users have 100 per IPv4 address or IPv6 /64 subnet pull limit.

Authenticated users have 200 pulls per account.

If docker.io doesn't work and you don't want make account, use another registry.

Regarding checksum issue:

1. Retry install
2. Clear cache and retry again
3. Make sure your network doesn't have issues

---

While using curl shows my phone can access to docker's registry and auth endpoint normally

Nope, it didn't show that you can access endpoint normally.

~ $ curl -I https://registry-1.docker.io/v2/
HTTP/2 401

Main registry endpoint show you Unauthorized, because you did not have token for access.

~ $ curl -I "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/ubuntu:pull"
HTTP/2 405

Here you have Method not allowed error (curl -I produces HEAD request). In both cases you violate access protocol for docker registry where you are supposed to obtain token first (mandatory even for anonymous user) and then use it for accessing registry.

[LCSOGthb]

docker.io has per-IP pull limits for anonymous/free users. Don't report this as issue of proot-distro. I won't fix that or change default registry.

Free users have 100 per IPv4 address or IPv6 /64 subnet pull limit.

Authenticated users have 200 pulls per account.

If docker.io doesn't work and you don't want make account, use another registry.

Regarding checksum issue:

1. Retry install
2. Clear cache and retry again
3. Make sure your network doesn't have issues

While using curl shows my phone can access to docker's registry and auth endpoint normally

Nope, it didn't show that you can access endpoint normally.

~ $ curl -I https://registry-1.docker.io/v2/
HTTP/2 401

Main registry endpoint show you Unauthorized, because you did not have token for access.

~ $ curl -I "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/ubuntu:pull"
HTTP/2 405

Here you have Method not allowed error (curl -I produces HEAD request). In both cases you violate access protocol for docker registry where you are supposed to obtain token first (mandatory even for anonymous user) and then use it for accessing registry.

Even if i authenticated proot-distro with my account it still failed with error code 400

[LCSOGthb]

~ $ proot-distro install ubuntu:24.04
[] Installing 'ubuntu:24.04' as 'ubuntu'...
[] Authenticating with registry (user credentials)...
[!] No cached manifest found for 'ubuntu:24.04' (aarch64).
[!] Failed to install: Network error: HTTP Error 400: Bad Request
[!] See 'proot-distro install --help' on how to install distribution image.

[LCSOGthb]

changing the images won't fix anything
~ $ proot-distro install debian:stable
[] Installing 'debian:stable' as 'debian'...
[] Authenticating with registry (user credentials)...
[!] No cached manifest found for 'debian:stable' (aarch64).
[!] Failed to install: Network error: HTTP Error 400: Bad Request
[!] See 'proot-distro install --help' on how to install distribution image.

[LCSOGthb]

docker.io has per-IP pull limits for anonymous/free users. Don't report this as issue of proot-distro. I won't fix that or change default registry.

Free users have 100 per IPv4 address or IPv6 /64 subnet pull limit.

Authenticated users have 200 pulls per account.

If docker.io doesn't work and you don't want make account, use another registry.

Regarding checksum issue:

1. Retry install
2. Clear cache and retry again
3. Make sure your network doesn't have issues

While using curl shows my phone can access to docker's registry and auth endpoint normally

Nope, it didn't show that you can access endpoint normally.

~ $ curl -I https://registry-1.docker.io/v2/
HTTP/2 401

Main registry endpoint show you Unauthorized, because you did not have token for access.

~ $ curl -I "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/ubuntu:pull"
HTTP/2 405

Here you have Method not allowed error (curl -I produces HEAD request). In both cases you violate access protocol for docker registry where you are supposed to obtain token first (mandatory even for anonymous user) and then use it for accessing registry.

I does wrong on some point but let me clear this for you

I cleared the cache everytime i retry the install command, still failed
I tried both Unauthorized and Authorized still failed
My network dosen't have any issue, changing DNS still won't fix the problem

[LCSOGthb]

You could see it only fetch auth.docker.io only

While my another phone could fetch registry-1.docker.io and production.cloudfront.docker.com and sucessfully install ubuntu

[LCSOGthb]

@sylirre Please review this again

[LCSOGthb]

@sylirre
~ $ proot-distro install ubuntu:24.04
[] Installing 'ubuntu:24.04' as 'ubuntu'...
[] Authenticating with registry (user credentials)...
[!] No cached manifest found for 'ubuntu:24.04' (aarch64).
[!] Failed to install: Network error: HTTP Error 400: Bad Request
[!] See 'proot-distro install --help' on how to install distribution image.
~ $ unset PD_DOCKER_AUTH
~ $ proot-distro install ubuntu:24.04
[] Installing 'ubuntu:24.04' as 'ubuntu'...
[] Authenticating with registry (anonymous)...
[] Fetching manifest for 'ubuntu:24.04'...
[] Fetching aarch64 manifest...
[] fff3795b4371: Downloading layer 1/1 (27.5 MiB)...
[] fff3795b4371: Applying layer 1/1...
[] Updating '/etc/resolv.conf'...
[] Updating '/etc/hosts'...
[] Registering Android-specific UIDs and GIDs...
[] Finished installation.

Reinstalled termux and retry, its the authentication issue

[sylirre]

1. I don't have such issue like you which means that scope is not proot-distro itself but networking.
2. Authentication should be done with user name and personal access token, not with password.
3. Repository includes integration tests to catch any issues related docker functionality.
4. If there would be an issue on proot-distro side, it would be consistently reproducible.
5. A lot of people use proot-distro. The error reported only by you, today.

You already said that GHCR works which rules out proot-distro issue.

While my another phone could fetch registry-1.docker.io and production.cloudfront.docker.com and sucessfully install ubuntu

This also rules out issue on proot-distro side.

I also told previously that docker.io applies pull restrictions on per-IP basis. This means if your CG-NAT public IP (same IP can be assigned to hundreds of clients) already exhausted the limit, you'll see an error.

[sylirre]

https://github.com/termux/proot-distro/actions/runs/28330251977/job/83927084264

[sylirre]

How to get personal access token:

Basically the same as one would do for Docker CLI

Then export PD_DOCKER_AUTH="username:dckr_pat_ManyCharactersHere". Password usable only for custom registries with regular basic auth.