---
title: "Install the Azure ML SDK for R"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Install the Azure ML SDK for R}
  %\VignetteEngine{knitr::rmarkdown}
  \use_package{UTF-8}
---

This article covers the step-by-step instructions for installing the Azure ML SDK for R.

You do not need run this if you are working on an Azure Machine Learning Compute Instance, as the compute instance already has the Azure ML SDK preinstalled.

## Install Conda

If you do not have Conda already installed on your machine, you will first need to install it, since the Azure ML R SDK uses **reticulate** to bind to the Python SDK. We recommend installing [Miniconda](https://docs.conda.io/en/latest/miniconda.html), which is a smaller, lightweight version of Anaconda. Choose the 64-bit binary for Python 3.5 or later.

## Install the **azuremlsdk** R package
The stable release of the Azure ML SDK can be installed from CRAN or the development version can 
be installed from GitHub. You will need **remotes** to install the **azuremlsdk** package.
``` {r install_remotes, eval=FALSE}
install.packages('remotes')
``` 

Then, you can use the `install_github` or `install_cran` functions to install the package.
``` {r install_azuremlsdk, eval=FALSE}
remotes::install_github('https://github.com/Azure/azureml-sdk-for-r')

remotes::install_cran('azuremlsdk', repos = 'https://cloud.r-project.org/')
```

If you are using R installed from CRAN, which comes with 32-bit and 64-bit binaries, you may need to specify the parameter `INSTALL_opts=c("--no-multiarch")` to only build for the current 64-bit architecture.
``` {r eval=FALSE}
remotes::install_cran('azuremlsdk', repos = 'https://cloud.r-project.org/', INSTALL_opts=c("--no-multiarch"))
```

## Install the Azure ML Python SDK
Lastly, use the **azuremlsdk** R library to install the [latest version of the Python SDK](https://pypi.org/project/azureml-sdk/).
``` {r install_pythonsdk, eval=FALSE}
azuremlsdk::install_azureml()
```

By default, `install_azureml()` creates a conda environment called 'r-reticulate', installs the Python SDK in that environment, and restarts the R session after installation (if running in RStudio).
If you would like to override the default version of the Python SDK, the environment name, or the Python version, you can pass in those arguments. If you would like to  delete the conda environment if it already exists and create a new environment, or not restart the R session after installation, you can also do so: 
``` {r eval=FALSE}
azuremlsdk::install_azureml(version = NULL, 
                            envname = "<your conda environment name>",
                            conda_python_version = "<desired python version>",
                            restart_session = FALSE,
                            remove_existing_env = TRUE)
```

## Test installation
You can confirm your installation worked by loading the library and successfully retrieving a run.
``` {r test_installation, eval=FALSE}
library(azuremlsdk)
get_current_run()
```

## Troubleshooting
-   If you're using the compute instance, the first time you run `library(azuremlsdk)` you may run into the following prompt:

    ```R
    > library(azuremlsdk)
    No non-system installation of Python could be found.
    Would you like to download and install Miniconda?
    Miniconda is an open source environment management system for Python.
    See https://docs.conda.io/en/latest/miniconda.html for more details.
    ```
    
    This is the reticulate package prompting the user if they want to have Miniconda installed (see [GitHub issue](https://github.com/rstudio/reticulate/issues/607)). Since the compute instance already has Anaconda, you can just respond "N" to the prompt. You will receive the message "Installation aborted", which just means that Miniconda won't be installed. You will only be prompted for this once for each new compute instance you spin up.

-   In step 3 of the installation, if you get ssl errors on windows, it is due to an
outdated openssl binary. Install the latest openssl binaries from
[here](https://wiki.openssl.org/index.php/Binaries).

- If installation fails due to this error:

  ```R
  Error in strptime(xx, f, tz = tz) : 
    (converted from warning) unable to identify current timezone 'C':
  please set environment variable 'TZ'
  In R CMD INSTALL
  Error in i.p(...) : 
    (converted from warning) installation of package ‘C:/.../azureml_0.4.0.tar.gz’ had non-zero exit
    status
  ```
  
  You will need to set your time zone environment variable to GMT and restart the installation process.
  
  ```R
  Sys.setenv(TZ='GMT')
  ```

- If the following permission error occurs while installing in RStudio,
  change your RStudio session to administrator mode, and re-run the installation command.

  ```R
  Downloading GitHub repo Azure/azureml-sdk-for-r@master
  Skipping 2 packages ahead of CRAN: reticulate, rlang
  Running `R CMD build`...
  
  Error: (converted from warning) invalid package
  'C:/.../file2b441bf23631'
  In R CMD INSTALL
  Error in i.p(...) : 
    (converted from warning) installation of package
    ‘C:/.../file2b441bf23631’ had non-zero exit status
  In addition: Warning messages:
  1: In file(con, "r") :
    cannot open file 'C:...\file2b44144a540f': Permission denied
  2: In file(con, "r") :
    cannot open file 'C:...\file2b4463c21577': Permission denied
  ```