Python and R runtimes

Open Settings → Runtimes to select the Python and R environments available to notebooks and the Agent. An environment's Ready status indicates successful detection/setup; its Enable switch separately controls availability to the Agent.

Choose an app-managed environment or an existing interpreter. Inspect its path, version, Ready state and Enable switch before use. System R and app-managed R can coexist.

Platform

macOSWindowsLinux

Your choice is kept across chapters.

Choose an environment for your project

Record the interpreter name, path and version. For a first Python analysis, prefer the isolated app-managed environment so package changes do not alter an unrelated research environment. Inspect Packages for required libraries before requesting installation. A successful package listing is a read-only check; it does not grant the agent permission to modify an external interpreter.

After an execution failure, distinguish an unavailable interpreter, a missing package, a denied request and a code error. Reinstallation is appropriate for a broken managed runtime, not for every failed analysis. If you need to reproduce a result, retain the input version and the code together with the runtime details.

Understand the main controls

Control	Purpose and boundary
Recheck	Refresh discovered interpreters and their status. The panel shows the last-check time. Unavailable during conflicting setup work.
Network settings	Open configuration for Notebook network protection. The banner explains whether sessions and package downloads are restricted to approved domains.
Let the Agent create environments	Control whether the Agent may create environments and set up missing runtimes. Turning this off does not remove explicit user setup or repair controls.
Add interpreter…	Open the system executable picker for an existing interpreter. Select the actual executable, then confirm its detected path and Ready status.
Download and set up	Prepare an app-managed environment when it is missing.
Cancel during setup	Request cancellation of the running setup. Wait for the operation to settle before starting another one.
Retry setup	Reattempt an unsuccessful setup after resolving its cause.
Enable [environment]	Make the environment available for agent selection. Disabling an in-use environment can require an impact confirmation.
Allow package install	Separate consent for an enabled external Python or R environment. R consent is limited to a selected personal library. Listing packages does not require installation consent.
Packages [count]	Open the installed-package inventory for that interpreter.
Reinstall	Open confirmation before rebuilding an app-managed environment.

Install an app-managed environment

Install app-managed Python

1. Find Python → App-managed environment.
2. Select Download and set up.
3. Read the progress message and wait. Cancel becomes available while setup is running.
4. On success, confirm conda: default-python, App-managed, and Ready.
5. Check the interpreter path and the Enable conda: default-python switch.

Confirm Ready, the selected interpreter path and the enabled state. Package counts and versions can vary with the installation source; do not use the screenshot’s temporary path as a permanent environment location.

Install app-managed R

1. Open Settings → Runtimes and scroll to R.
2. Under App-managed environment, select Download and set up. An existing system R does not prevent you from installing this separate environment.
3. Wait for download and environment creation to finish. Keep the application open and read any error before retrying.
4. Confirm conda: default-r, App-managed, Ready, and an enabled switch.
5. Open Packages. Enter r-base in Filter packages to check the installed R version and channel; clear the filter to see all packages.

Confirm that filtering r-base returns the installed R package, with its version and channel. Package totals reflect your environment and may differ from the screenshot.

Connect an existing interpreter

Use R already installed on your computer

Select Recheck and inspect the detected R path and version. If your interpreter is absent, use Add interpreter… to select its executable. Ready and Enable have different meanings: detection confirms that the interpreter is available; enabling makes it selectable by the Agent.

In an R Notebook, check R.home() to confirm the environment in use. To install dependencies, authorize a personal library using the external R installation steps.

A detected path such as /opt/homebrew/bin/R identifies a system installation.

Register and use external Python

1. Prepare the Python environment you intend to use.
2. Select Add interpreter…, choose its Python executable, and check Ready, the path and version.
3. Use Recheck to verify detection, then enable that specific environment.
4. Ask the Agent to select it explicitly for the Notebook.
5. Print sys.executable and the Python version before relying on its installed libraries.

If a symlink interpreter cannot be selected in the macOS file picker, select the actual executable of the intended environment. Confirm sys.executable after binding it. Use a stable installation path rather than the screenshot’s temporary example path.

Package permission and installation outcome

For a new package in an external Python environment, check Allow package install first. After granting permission, wait for installation to finish and verify the import in the same environment before continuing.

If installation reports 403 Forbidden or destination resolves to a non-public network address, inspect the affected hostname and follow Network before retrying. These errors concern network access and do not prove that the package is unavailable. Keep network protection enabled.

Disable an environment used by a Notebook

Select its Enable switch and read the active/idle kernel counts before confirming. Disabling can close the kernel; after re-enabling, select an available runtime for the session again. This panel provides enable/disable controls rather than a separate Remove interpreter action.

Install packages in external R

Use this when your existing R interpreter works but needs an additional package. The app grants installation access to one existing personal library, not to system or site libraries.

1. In Settings → Runtimes, enable the intended external R environment and confirm its path/version.
2. Under Personal R package library, inspect the detected location or select an eligible library. If none is detected, use Advanced options → Choose library folder… to select an existing writable personal library visible to that R interpreter. This action does not create a folder.
3. Enable Allow package install. Read the selected path before authorizing: other projects using this library may see the installed package changes.
4. Request the required package through the app’s package-management operation, naming this R environment. Follow the installation result and any kernel-restart instruction.
5. Run R.home(), .libPaths(), library(PACKAGE_NAME) and packageVersion("PACKAGE_NAME") in that environment, replacing the package placeholder. Confirm that the intended library is used before continuing the analysis.

Turn off Allow package install to revoke future installation consent. It does not uninstall packages already written. Revoke consent before choosing another library. If no eligible folder exists, prepare a personal R library outside the app or use an app-managed environment; do not choose the system library to bypass a failed check.

Restore packages from captured locks

For a saved result, open Provenance → Environment and inspect the captured lock. Use Download bundle when offered. Read the bundle’s instructions and prerequisites before restoring anything.

External R requires an available renv installation and a supported renv.lock; external Python needs an existing supported requirements lock with pinned hashes. An interpreter path and a list of package names alone are not sufficient. The captured interpreter, platform, architecture and package-manager requirements must match the restore environment.

Extract the bundle, choose a new writable destination that you own, and run its included restore-packages.py with the actual interpreter and destination paths, following the bundled instructions. The script checks prerequisites and checksums before restoring packages, then checks their effective versions and paths. If a check fails, resolve that condition instead of editing the lock to force success. Open-Science does not adopt or delete this external destination.

This is conditional package restoration, not a full environment clone. Reopen the result and use Reproducibility when a supported captured recipe is available to compare outputs.

Inspect installed packages

Select Packages on the intended Python card. The dialog shows that environment’s path, package source and status.

Enter a package name such as numpy in Filter packages, inspect its version and channel, then clear the filter to restore the list. Use Close to return.

The table columns are Name, Version, Build, and Channel. A dash in Build means no build value is shown. This dialog is an inventory: it has no package-install or uninstall buttons. Do not look for an “Install package” field inside this dialog.

Verify the environment with a real analysis

Run a small calculation in the chosen environment, reopen its output and compare it with the shared baseline. Follow R Notebook for execution and export.

The data-quality workflow provides a Python route using existing dependencies. A successful calculation does not demonstrate that new packages can be installed or a kernel restarted.

If an import fails, inspect the selected runtime and its installed packages. For a download rejected because a hostname resolves to a reserved address, follow Network. Running code with existing packages does not establish that additional packages can be installed.

Before another analysis, inspect its required packages in the selected environment. Use the supported package-management operation if necessary, read the actual result, follow any restart requirement, and verify the import. A permission approval, progress card or Ready interpreter is not an import test.

For a saved result with incomplete environment or execution evidence, open Provenance and inspect the missing information. To prepare a new version for a reproducibility check, follow environment preparation. Matching a numeric result does not fill missing provenance.

Confirm the active interpreter

After preparing Python or R, run the following commands in the corresponding Notebook language to check its actual version and path. Settings may list several environments; use the current run's output to identify the one in use.

Python:

import sys
print(sys.version)
print(sys.executable)

R:

R.version.string
R.home()

Next, read a small project table, check its row count and save the result. After reopening the app, run the check again before continuing an analysis. A readable historical report does not mean the previous in-memory variables still exist. See Notebook and execution evidence for Notebook controls.

Maintain and repair environments

Cancel setup and retry

During Download and set up, choose Cancel and wait for Runtime setup cancelled. Choose Retry setup, wait for Ready, and open Packages to inspect the environment. Do not start a second setup while the first operation is still settling.

Reinstall a managed environment

1. Save needed reports and record any packages you added.
2. Select Reinstall on the intended managed environment.
3. Read the impact notice, then choose Reinstall runtime.
4. Wait for Ready and inspect Packages.
5. Start a new Notebook cell and reopen your saved inputs and outputs.

Reinstallation deletes and recreates the environment. In the exercised recovery, an active cell was cancelled with Run cancelled: the runtime was stopped while this cell was executing. The old Notebook history remained visible, but its namespace no longer existed. A fresh cell confirmed that an earlier variable was absent; the unchanged CSV still returned 12 rows and 269,027,617 counts, and the saved report reopened.

Retained files and retained kernel memory are different. Recreate variables by rerunning the required code. Additional packages may need reinstalling; successful recovery of the base environment does not establish recovery of every added dependency.

Development build: micromamba not found

The first attempt in the source build failed before provisioning because the development process could not locate micromamba.

The packaged application includes this binary. For a source build, point OPEN_SCIENCE_MICROMAMBA_BIN at a valid micromamba executable in that process's launch environment and restart the development instance. Use the binary path from a compatible installation and confirm it is executable before relaunching.

This environment variable is a development setup detail, not a field in the Runtimes page. Do not delete an environment directory to work around this discovery error.