Prerequisites

• R 4.2.0 or later (R 4.1.x is not supported: it is the last Windows R with 32-bit multiarch, and reticulate 1.44.0 or later does not build for 32-bit Windows)
• reticulate 1.44.0 or later (earlier versions are incompatible with uv 0.8.0 and later, and fail with could not find a Python environment for /)

When synapser is loaded, it declares its Python requirement (synapseclient[pandas], pinned to the version synapser wraps) via reticulate::py_require(). If reticulate does not find another Python configured on your machine, it uses uv to download a compatible Python and the Synapse Python client into a managed environment, so you DO NOT need to install Python yourself. synapser supports Python 3.10 to 3.14 and does not request a specific one, so reticulate picks its own default: two minor versions behind the newest stable release (Python 3.12 as of reticulate 1.46.0). Run reticulate::py_config() to see which version you got. The first load may take a minute; later loads reuse the cached environment.

By default, reticulate only uses this managed environment when no other Python takes precedence in its Order of Discovery. In particular, synapser will use a different Python if any of the following apply:

• The RETICULATE_PYTHON or RETICULATE_PYTHON_ENV environment variable is set (this includes selecting a Python interpreter in RStudio’s Project or Global Options).
• A Python virtual environment is activated (VIRTUAL_ENV is set), or your working directory contains a .venv, venv, or similar virtual environment.
• A virtual environment named r-reticulate exists (for example, ~/.virtualenvs/r-reticulate, created by earlier versions of these instructions).

In those cases synapser installs the Synapse Python client into that Python, which must be version 3.10 to 3.14. To use the managed environment instead, remove the conflicting setting, e.g. reticulate::virtualenv_remove("r-reticulate"), and restart R. You can check which Python synapser is using with reticulate::py_config().

Install SynapseR from GitHub

The synapser source code is on GitHub at Sage-Bionetworks/ synapser. In stalling from GitHub is useful if you want to try changes t hat have not been released to the Synapse R repository (RAN ) yet. For everyday use, install a released version from RA N as shown above.

1. Install the remotes package if you don’t already h ave it:

   if (!require("remotes", quietly = TRUE)) {
     install.packages("remotes")
   }

2. Install synapser from GitHub. Without a ref, this installs the default branch, develop, which contains the latest development changes:

   remotes::install_github("Sage-Bionetworks/synapser")

3. Optionally, install a specific branch or release by passing ref:

   # The latest release
   remotes::install_github("Sage-Bionetworks/synapser", ref
    = "master")
   
   # A specific release, by its tag (for example, 2.1.5)
   remotes::install_github("Sage-Bionetworks/synapser", ref
    = "3.0.0")

4. Restart R, then load synapser to confirm the install ation:

   library(synapser)
   packageVersion("synapser")

Install R

1. Install R v4.2.0 or later
   1. Download links
      1. For macOS users, you can select a mirror and download R here
      2. For Windows and Linux users, you can select a mirror and download R here NOTE: R 4.1.x and earlier are not supported. On Windows, R 4.1.x is the last release with 32-bit multiarch, which the required version of reticulate cannot build for.
2. Install RStudio Desktop
3. For Windows users, if you intend to run the project from outside RStudio Desktop (for example: VS Code or Terminal) the only additional step is to add R to system path: C:\Program Files\R\R-4.2.0\bin\R.exe

SynapseR Installation (WIP)

Install from RStudio

• This guide assumes you have Python, R, and RStudio Desktop installed as described above.
• This guide will presume most users want to install and work with Synapse from RStudio Desktop.

Once that’s complete, we are ready to move on to selecting our desired Python interpreter. If the above fails, follow the steps below, then run the installation.

1. Select your project’s desired Python interpreter

To select our desired Python interpreter, let’s navigate to Tools > Project Options (or Global Options)

RStudio Project Options menu

2. Let’s select Python from the list of options on the left hand side:

RStudio Project Options with Python selected in left panel

3. Click Select

Python interpreter selection dialog

4. Select the Virtual Environments tab:

Python virtual environments tab

5. Click on Select to choose our desired Reticulate virtual environment:

Selected reticulate virtual environment in RStudio

In the example above, we can see that my desired Python 3.9.6 environment (your python version may be different, and that’s ok) installed from the official Python installer and NOT the Python version that shipped on macOS - is selected.

# This is a bash session - Not R code
# Verify pyenv is working and Python 3.10 is installed
pyenv versions
python --version  # Should show Python 3.10
pyenv version

# This is a bash session - Not R code
# Verify you have Python 3.10
python3 --version  # Should show Python 3.10.x
which python3

install.packages("synapser", repos = c("http://ran.synapse.org", "https://cloud.r-project.org"))

(Optional) Managing Python

This step is optional, but recommended if you plan to use multiple Python versions or want full control over your Python environment. Most synapser users do not need pyenv unless they have special requirements. ## Option 1: Using pyenv (Recommended)

We strongly recommend using pyenv to manage Python versions, as it provides better compatibility and easier version switching. This is especially important for synapser, which requires Python 3.10-3.14.

Find more information about pyenv here

# Using Homebrew (recommended)
brew install pyenv

# Or using the automatic installer
curl https://pyenv.run | bash

# Install dependencies first
sudo apt-get update
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev \
libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python3-openssl git

# Install pyenv
curl https://pyenv.run | bash

# Install dependencies first
sudo yum groupinstall -y "Development Tools"
sudo yum install -y zlib-devel bzip2-devel readline-devel sqlite-devel libffi-devel \
openssl-devel xz-devel libffi-devel

# Install pyenv
curl https://pyenv.run | bash

echo $SHELL
# Common outputs:
# /bin/bash  -> use ~/.bashrc or ~/.bash_profile
# /bin/zsh   -> use ~/.zshrc

# Add to ~/.bashrc (Linux) or ~/.bash_profile (macOS)
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# For macOS bash users, also add to ~/.bash_profile
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile
echo 'eval "$(pyenv init -)"' >> ~/.bash_profile

# Add to ~/.zshrc
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# For bash
nano ~/.bashrc    # or ~/.bash_profile on macOS

# For zsh  
nano ~/.zshrc

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

# Reload your shell configuration
source ~/.bashrc    # for bash on Linux
source ~/.bash_profile  # for bash on macOS
source ~/.zshrc     # for zsh

# OR restart your terminal

pyenv --version
which pyenv  # Should show /home/username/.pyenv/bin/pyenv

# List available Python versions
pyenv install --list | grep " 3\.10"

# Install Python 3.10 (recommended version)
pyenv install 3.10

# Set as global default (optional)
pyenv global 3.10

# Or set as local for your project directory
cd /path/to/your/project
pyenv local 3.10

# Verify installation
python --version  # Should show Python 3.10
pyenv version