This error occurs during Docker image builds when apt-get cannot find a valid version of the requested package to install. The most common fix is running apt-get update before installation to refresh the package index.
The "Package has no installation candidate" error appears when the APT package manager knows a package exists (it's referenced somewhere) but cannot find a downloadable version in any configured repository. Unlike "Unable to locate package" which means APT has never heard of the package, this error indicates APT has some metadata about the package but no actual installation files are available. In Docker containers, this typically happens because base images ship with minimal or completely empty package indexes to reduce image size. When you run `apt-get install` without first running `apt-get update`, APT either has no package index at all or has a stale index that references packages that have been moved, renamed, or removed from the repositories. This is especially common with packages that exist in specific repositories (like "universe" or "multiverse" in Ubuntu) that may not be enabled by default in minimal Docker images.
The most common fix is to refresh the package index before installing. Always combine apt-get update with apt-get install in the same RUN command:
FROM ubuntu:22.04
# Wrong - Missing apt-get update
RUN apt-get install -y vim
# Correct - Update package index first
RUN apt-get update && apt-get install -y vimThe && operator ensures both commands run in sequence and if update fails, installation won't proceed. This prevents Docker from using a cached (stale) package index from a previous build layer.
If you have apt-get update and apt-get install in separate RUN commands, Docker caches each layer independently. This means a cached update can become stale:
# Wrong - Separate RUN commands (update gets cached)
RUN apt-get update
RUN apt-get install -y vim # May fail if update layer is cached
# Correct - Single RUN command
RUN apt-get update && apt-get install -y \
vim \
curl \
git \
&& rm -rf /var/lib/apt/lists/*The rm -rf /var/lib/apt/lists/* at the end removes the package cache to reduce image size.
Some packages are only available in additional Ubuntu repositories. If the package isn't in the main repository, enable universe or multiverse:
FROM ubuntu:22.04
# Enable universe repository for additional packages
RUN apt-get update && \
apt-get install -y software-properties-common && \
add-apt-repository universe && \
apt-get update && \
apt-get install -y <package-name>Alternatively, manually edit sources.list:
RUN echo "deb http://archive.ubuntu.com/ubuntu/ jammy main universe" > /etc/apt/sources.list && \
echo "deb http://archive.ubuntu.com/ubuntu/ jammy-updates main universe" >> /etc/apt/sources.list && \
apt-get update && \
apt-get install -y <package-name>The package may not exist in your Ubuntu/Debian version. Check availability by running a temporary container:
# Start temporary container with your base image
docker run -it --rm ubuntu:22.04 bash
# Inside container, update and search for package
apt-get update
apt-cache search vim
apt-cache policy vimThe apt-cache policy <package> command shows available versions and which repository provides them. If nothing appears, the package doesn't exist in that distro version.
For packages that have been renamed or removed, search online for alternatives or use a different base image:
# Python 2 removed from newer Ubuntu - use older image
FROM ubuntu:20.04
RUN apt-get update && apt-get install -y python2If you suspect Docker is using cached layers with stale package indexes, rebuild without cache:
# Rebuild image without using cache
docker build --no-cache -t myimage .
# Or pull fresh base image first
docker pull ubuntu:22.04
docker build --no-cache -t myimage .This forces Docker to run all commands fresh, including apt-get update, ensuring the latest package index is downloaded.
Understanding the difference between apt errors: "Unable to locate package" means APT has no knowledge of the package at all. "Package has no installation candidate" means APT knows the package exists (often because another package depends on it) but cannot find installable files. Both typically resolve with apt-get update.
Minimal vs full base images: Images like ubuntu:22.04 are intentionally minimal. They may not include all repository definitions. Consider using buildpack-deps:jammy or similar images that come with common development packages pre-installed.
Debian vs Ubuntu repositories: Debian-based images (like debian:bookworm) have different repository names (main, contrib, non-free). Make sure you're using the correct repository syntax for your base image.
DEBIAN_FRONTEND=noninteractive: Some packages prompt for configuration during installation. Set this environment variable to prevent interactive prompts that would hang Docker builds:
ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y tzdataUsing aptitude for dependency resolution: In rare cases, aptitude can resolve complex dependency issues better than apt-get:
RUN apt-get update && \
apt-get install -y aptitude && \
aptitude install -y problematic-packageNetwork/mirror issues: If apt-get update itself fails, you may be hitting rate limits or network issues. Try specifying a different mirror or check if you're behind a corporate proxy that blocks apt repositories.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub