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:
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:
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.
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.
- Select a repository from the list on the left of the page, then click the Setup button at the top of the screen.
- Ensure the Latest button is selected (blue)
- The configured repository URL is displayed below the calendar
- 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)
- Select a repository from the list on the left of the page, then click the Setup button at the top of the screen.
- 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.
- The configured repository URL is displayed below the calendar
- 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:
- Use of more than one source in a repository.
- Use of a source that does not support date aliases.
- 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).
- 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:
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:
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:
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.
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:
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:
-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:
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:
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:
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.
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.
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.