What does the ADD instruction do?

The ADD instruction is a Dockerfile command used to copy new files, directories, or remote file URLs from a source and add them to the filesystem of the image at a specified destination path [citation:2]. While it serves a similar purpose to the COPY instruction, ADD includes two additional functionalities: it can automatically extract compressed archive files (such as .tar, .gz, or .bz2) directly into the destination, and it can fetch files from remote URLs [citation:3][citation:6]. This makes ADD a more powerful but also more complex command than its simpler counterpart, COPY.

The ADD command can handle three types of sources: local files, local directories, and remote URLs [citation:6]. When the source is a local compressed archive in a recognized format (identity, gzip, bzip2, or xz), ADD automatically extracts its contents at the destination [citation:3][citation:10]. When the source is a URL, ADD downloads the file and places it in the destination directory [citation:5]. For local files that are not archives, ADD behaves similarly to COPY, simply copying the files without any additional processing [citation:10].

Despite its additional capabilities, Docker's official documentation and best practices strongly recommend using COPY instead of ADD unless you specifically need the automatic archive extraction or URL downloading features [citation:1][citation:7]. COPY is more transparent and predictable since it only performs file copying operations, making Dockerfiles easier to understand and maintain [citation:3][citation:7]. For downloading remote files, many experts recommend using RUN with curl or wget instead of ADD, as this provides better control and doesn't create unnecessary image layers [citation:3][citation:7].