Skip to content

User Guide#

This guide contains an overview of Package Manager's web-based user interface, as well as instructions for configuring your data science environment to install packages from Package Manager.

Overview and Navigation#

After clicking the Get Started button on the welcome page, you are taken to the main page:

Package Manager repository view screenshot, with repository list on left and repository packages, activity, and setup tabs on top

Highlighted above on the left navigation bar is the list of package repositories configured in Package Manager. Click on a repository to work with.

At the top of the screen , the name of the selected repository is displayed, followed by links to view additional details:

Link Description
Packages Search or browse the packages available in the repository
Activity View a log of when packages were added, archived, or deleted from the repository
Setup Instructions for configuring your environment to access packages from the repository
What's New News about the latest feature updates in Package Manager

For R repositories, in the top right corner of the page the R Distribution can be selected.

Getting Started Using Package Manager#

The Setup page provides instructions to configure your R or Python environment to obtain its packages from Package Manager.

Setting up your environment to use Package Manager consists of the following steps:

  1. Set the R distribution corresponding to your installation environment
  2. Obtain the desired repository URL for your needs
  3. Configure your R environment to use the new repository URL
  1. Obtain the desired repository URL for your needs
  2. Configure your Python environment to use the new repository URL

Setting Your Distribution for R Binary Packages#

Package Manager provides R packages for Windows and many popular Linux distributions. By configuring which distribution you are installing to, it can ensure a binary is compatible with your environment and also will display instructions on how to install any other system dependencies you may need.

Note

If you don't intend to use pre-built binary packages, but prefer to build packages yourself from the original source, select "Source" as your distribution.

To set your distribution, click the Distribution link in the top right corner of the screen and select your desired installation environment.

Package Manager screenshot with distribution selector highlighted in orange

Note

Python repositories handle binaries differently, so it is not necessary to set a distribution.

Next Steps: Obtain a repository URL for your environment.

Obtaining a repository URL#

Package installation tools in R and Python are typically configured, by default, to access packages from one or more public package repositories, such as CRAN, Bioconductor, or the Python Package Index (PyPI). To install packages from Package Manager, your environment must be reconfigured by changing the repository URL in your client.

Depending on your project needs, there are several different options for your repository URL.

Getting the latest packages available#

In most cases, you will probably want to use the latest and greatest versions of packages available. This will allow your package management tools to detect and install upgrades when available, and ensure you're using the most updated package features available.

Package Manager Setup tab screenshot, showing snapshot calendar with latest URL selected

  1. Select a repository from the list on the left of the page, then click the Setup button at the top of the screen.
  2. Ensure the Latest button is selected (blue)
  3. The configured repository URL is displayed below the calendar
  4. Click the Copy button to copy the URL to your clipboard

Next Steps: Configure your R or Python environment to use the repository URL

Getting frozen URLs for improving reproducibility#

A popular feature of Package Manager is date-based snapshots. A user specifies a date, and Package Manager provides a collection of packages limited to what was available on that date.

Info

Posit provides snapshots of public repositories every business day, but not on weekends or holidays. The calendar of available snapshot dates is shown on the page. (details)

Package Manager Setup tab screenshot, showing snapshot calendar with binary and frozen URL

  1. Select a repository from the list on the left of the page, then click the Setup button at the top of the screen.
  2. Scroll the calendar to select a snapshot date. Dates with an available snapshot are indicated by a box around the day. The Freeze button will be selected automatically.
  3. The configured repository URL is displayed below the calendar
  4. Click the Copy button to copy the URL to your clipboard

Tip

For projects that require strict reproducibility, selecting the Lock Package Data check box will guarantee you always receive same packages. However, for improved flexiblity, we recommend leaving this unchecked to allow for simpler repository URLs.

Next Steps: Configure your R or Python environment to use the repository URL

More about frozen URLs

Frozen URLs encode information about all the sources in the repository, as well as the snapshot date.
Below the URL, you may see text describing the sources and snapshots included. Package Manager tries to keep the URL as simple as possible, but frequently needs to encode more complicated information, so you'll see some random-looking text after the date in the URL. Any of these criteria results in an encoded URL:

  1. Use of more than one source in a repository.
  2. Use of a source that does not support date aliases.
  3. Selecting a date that a date alias can't apply to (a date where a snapshot doesn't exist, and a past snapshot must be referenced instead).
  4. Selecting the Lock Package Data check box.

When you get an encoded URL, Package Manager also provides you with information about what the encoded URL contains. For example, the screenshot below shows a URL from a repository that contains two sources, CRAN and bioc-3.16:

Screenshot of decoded URL contents

Note that the Bioconductor source does not pin to a date - only to the Bioconductor version. For more information, see Bioconductor source details.

Configuring R Environments#

Once you have obtained the repository URL, your environment must be configured to use the URL to download and install packages.

Base R#

To configure R to use Package Manager as its CRAN repository, set the repos option to use the repository URL:

R
options(repos = c(CRAN = "https://packagemanager.posit.co/cran/__linux__/centos7/latest"))

Alternatively, instead of replacing your default URL, additional repositories can be added to your existing configuration. For example:

R
local({
  repos <- c(PackageManager = "https://packagemanager.posit.co/cran/__linux__/centos7/latest")
  repos["LocalPackages"] <- "https://packagemanager.posit.co/local/__linux__/centos7/latest"

  # add the new repositories first, but keep the existing ones
  options(repos = c(repos, getOption("repos")))
})
# verify the current repository list
getOption("repos")
#                                                      PackageManager
#  "https://packagemanager.posit.co/cran/__linux__/centos7/latest"
#                                                       LocalPackages
# "https://packagemanager.posit.co/local/__linux__/centos7/latest"
#                                                                CRAN
#                                       "https://cloud.r-project.org"

The same code can be added to your R startup file (Rprofile.site or .Rprofile) to maintain the repository configuration across R sessions. See our article on managing R startup files for more details.

Tip

If you are installing packages on Linux and want to take advantage of pre-built binary packages for speed and reliability, follow the instructions in Configuring the R User Agent Header to set up or verify your configuration.

RStudio Desktop or Posit Workbench#

In RStudio Desktop or Posit Workbench, repository settings are configured through the Global Options menu available from the Tools section of the main toolbar. In the Packages submenu, paste the repository URL into the "Primary CRAN repo" field or click Add to include this repository as a secondary repo.

RStudio Desktop Global Options screenshot for setting CRAN repository

Your Posit Workbench administrator can also configure the default repository for all users to point to Package Manager. See Configuring Posit Workbench for more information.

Configuring Python Environments#

Once you have obtained the repository URL, your environment must be configured to use the URL to download and install packages.

pip#

To configure pip globally for all projects, call the pip config command to set the global.index-url to your repository URL:

Terminal
pip config set global.index-url https://packagemanager.posit.co/pypi/latest/simple

Tip

If using virtual environments with venv, activate your virtual environment first, then run the pip config command above to set the Package Manager repository for that specific environment.
Refer to Installing packages using pip and virtual environments in the Python documentation for more information.

requirements.txt#

To use a Package Manager repository with a specific project defined by a requirements.txt file, add -i [repositoryURL] to the top of your file, for example:

requirements.txt
-i https://packagemanager.posit.co/pypi/latest/simple
pandas
scipy
...

Viewing Package Details#

The Packages page allows you to search or browse available packages. To search for a package, enter the package name, or a partial search term into the search box:

Package Manager packages view with search box highlighted

A list of packages matching the search term is displayed along with a brief description of the package provided by the author.

Select a package from the search results list to view details about the package:

Package Manager R package overview pane

Many packages contain additional information or documentation such as a Readme. If available, those buttons will be shown next to the Overview button under the package title as highlighted above.

Note

In the Package view, the "Published" date represents the date that a package was published to CRAN, Github, etc. while the "Available As Of" date represents when the package was available from this specific Package Manager server.

Some packages also require additional system prerequisites to be installed on your system. If so, the instructions for installing those prerequisites for your specific environment will be shown on the right pane under Install System Prerequisites:

Package Manager system prerequisites snapshot

Package Manager Python package overview pane

Many packages contain additional information or documentation such as a Description. If available, those buttons will be shown next to the Overview button under the package title as highlighted above.

Reviewing Package Activity#

The Activity Log displays a log entry for each time a change is made to the repository, which includes adding, archiving, or deleting a package version.

Screenshot of the Activity tab showing snapshot records

On the left of each row, click the arrow to expand and examine which changes occurred in a given snapshot.

If your repository subscribes to more than one source, you'll see a drop-down menu, allowing you to select which source to show activity from. Only one source's activity can be shown at a time.

Activity page showing drop-down menu to select one of many sources

For public sources (CRAN, Bioconductor, and PyPI) package updates are synced every business day from the Posit Package Service. These appear as a "Sync" action in the Activity Log.

What's New in Package Manager?#

The What's New page highlights the newest feature improvements in Package Manager. For a complete list of features, bug fixes, and other important changes, click the release notes link at the top of the page.

Copyright © Posit Software, PBC. All Rights Reserved.