download.file {utils}R Documentation

Download File from the Internet


This function can be used to download a file from the Internet.


download.file(url, destfile, method, quiet = FALSE, mode = "w",
              cacheOK = TRUE,
              extra = getOption("download.file.extra"))



A character string naming the URL of a resource to be downloaded.


A character string with the name where the downloaded file is saved. Tilde-expansion is performed.


Method to be used for downloading files. Current download methods are "internal", "wininet" (Windows only) "libcurl", "wget" and "curl", and there is a value "auto": see ‘Details’ and ‘Note’.

The method can also be set through the option "download.file.method": see options().


If TRUE, suppress status messages (if any), and the progress bar.


character. The mode with which to write the file. Useful values are "w", "wb" (binary), "a" (append) and "ab". Only used for the "internal" method.


logical. Is a server-side cached value acceptable?


character vector of additional command-line arguments for the "wget" and "curl" methods.


The function download.file can be used to download a single file as described by url from the internet and store it in destfile. The url must start with a scheme such as http://, ftp:// or file://.

If method = "auto" is chosen (the default), "libcurl" is chosen if available (see below) for https:// and fttps:// URLs, method "internal" is chosen otherwise and for file:// URLs, and for the others provided capabilities("http/ftp") is true (which it almost always is). Otherwise methods "wget" and "curl".

Support for method "libcurl" is optional: use capabilities("libcurl") to see if it is supported on your build. It provides (non-blocking) access to https:// and ftps:// URLs. There is support for simultaneous downloads, so url and destfile can be character vectors of the same length greater than one. For a single URL and quiet = FALSE there a progress bar is shown in interactive use.

For methods "wget" and "curl" a system call is made to the tool given by method, and the respective program must be installed on your system and be in the search path for executables. They will block all other activity on the R process until they complete: this may make a GUI unresponsive.

cacheOK = FALSE is useful for http:// URLs, and will attempt to get a copy directly from the site rather than from an intermediate cache. It is used by available.packages.

By default only the "libcurl" and "wget" methods follow http:// redirections. (For method "curl" use argument extra = "-L". To disable redirection in wget, use extra = "--max-redirect=0".)

The remaining details apply to method "internal" only.

Note that https:// URLs are not supported by the internal method.

See url for how file:// URLs are interpreted, especially on Windows. This function does decode encoded URLs.

The timeout for many parts of the transfer can be set by the option timeout which defaults to 60 seconds.

The level of detail provided during transfer can be set by the quiet argument and the option. The details depend on the platform and scheme, but setting to 0 gives all available details, including all server responses. Using 2 (the default) gives only serious messages, and 3 or more suppresses all messages.

A progress bar tracks the transfer. If the file length is known, an equals sign represents 2% of the transfer completed: otherwise a dot represents 10Kb.

Code written to download binary files must use mode = "wb", but the problems incurred by a text transfer will only be seen on Windows.


An (invisible) integer code, 0 for success and non-zero for failure. For the "wget" and "curl" methods this is the status code returned by the external program. The "internal" method can return 1, but will in most cases throw an error.

Setting Proxies

This applies to the internal code only.

Proxies can be specified via environment variables. Setting no_proxy to * stops any proxy being tried. Otherwise the setting of http_proxy or ftp_proxy (or failing that, the all upper-case version) is consulted and if non-empty used as a proxy site. For FTP transfers, the username and password on the proxy can be specified by ftp_proxy_user and ftp_proxy_password. The form of http_proxy should be or where the port defaults to 80 and the trailing slash may be omitted. For ftp_proxy use the form where the default port is 21. These environment variables must be set before the download code is first used: they cannot be altered later by calling Sys.setenv.

Usernames and passwords can be set for HTTP proxy transfers via environment variable http_proxy_user in the form user:passwd. Alternatively, http_proxy can be of the form for compatibility with wget. Only the HTTP/1.0 basic authentication scheme is supported.

Much the same scheme is supported by method = "libcurl", including no_proxy, http_proxy and ftp_proxy, and for the last two a contents of [user:password@]machine[:port] where the parts in brackets are optional. See for details.

Secure URLs

Methods which access https:// and ftps:// URLs usually try to verify their certificates. This is usually done using the CA root certificates installed by the OS (although we have seen instances in which these got removed rather than updated).

This is an issue for method = "libcurl" on Windows, where the OS does not provide a suitable CA certificate bundle, so by default on Windows certificates are not verified. To turn verification on, set environment variable CURL_CA_BUNDLE to the path to a certificate bundle file, usually named ‘ca-bundle.crt’ or ‘curl-ca-bundle.crt’. (This is normally done for a binary installation of R, which installs ‘etc/curl-ca-bundle.crt’.)


Files of more than 2GB are supported on 64-bit builds of R; they may be truncated on some 32-bit builds.

Methods "wget" and "curl" are mainly for historical compatibility, but can be used for URLs (e.g., https:// URLs or those that use cookies or redirection) which the internal method does not support where the "libcurl" method is not available.

Method "wget" can be used with proxy firewalls which require user/password authentication if proper values are stored in the configuration file for wget.

wget ( is commonly installed on Unix-alikes (but not OS X). Windows binaries are available from Cygwin, gnuwin32 and elsewhere.

curl ( is installed on OS X and commonly on Unix-alikes. Windows binaries are available at that URL.

See Also

options to set the HTTPUserAgent, timeout and options.

url for a finer-grained way to read data from URLs., available.packages, download.packages for applications.

Contributed package RCurl provides more comprehensive facilities to download from URLs.

[Package utils version 3.3.0 Index]