Interpreter Settings

Workbench | Preview

Positron Pro sessions enable several settings that are particularly useful for Workbench Administrators. These settings allow the administrator to configure which Python and R interpreters are available to their users. These settings can be added to any of the User and group settings templates.

Interpreter Startup Behavior Settings

The interpreters.startupBehavior setting controls how interpreters are started in Positron Pro windows. Startup behavior can be set per-language or set generally, for all interpreters.

The default auto configuration is suitable for teams using both R and Python regularly. If your team is specialized towards R or Python, refer to the Per-language startup behavior section for examples of how to configure startup behavior for specific languages.

Options

  • always: An interpreter always starts when a new Positron Pro window is opened; the last used interpreter starts if available, and a default is otherwise chosen.
  • auto: An interpreter starts when needed or if it was previously used in the workspace. This is the default.
  • recommended: An interpreter starts when the extension providing the interpreter recommends it.
  • manual: Interpreters only start when manually selected.
  • disabled: The setting disables the interpreters. Users cannot select an interpreter.

By following the instructions in the Configuring interpreter startup Positron documentation, Positron Pro users can configure interpreter startup behavior in their personal user settings as well.

Per-language startup behavior

Per-language interpreter startup behavior can be set using the [language] key in the settings.

For example, if a user or group mainly uses Python, set the R interpreter startup behavior to manual to prevent R from starting automatically but still allow team members to start an R interpreter manually.

"[r]": {
    "interpreters.startupBehavior": "manual"
}

Alternatively, if a user or group doesn’t use one of R or Python, set the corresponding startup behavior to disabled to hide those interpreters from Positron Pro:

// Disable Python
"[python]": {
    "interpreters.startupBehavior": "disabled"
},

// Disable R
"[r]": {
  "interpreters.startupBehavior": "disabled"
},

General interpreter startup behavior

To set the startup behavior for all interpreters, use the interpreters.startupBehavior setting without a language key.

Note

If any per-language startup behavior is set, it takes precedence over the general interpreter startup behavior setting.

For example, to set the startup behavior to manual for all interpreters:

"interpreters.startupBehavior": "manual"

Python Interpreter Settings

These settings configure which Python interpreters are available in Positron Pro. Use these settings to specify the default Python interpreter, include additional Python installations, exclude specific Python installations, and override the list of available Python installations.

python.defaultInterpreterPath

This setting specifies the absolute path to a Python interpreter, highlighting it as the default for new workspaces and prioritizing it in the Positron Pro interpreter selection UI.

Once a user affiliates a Python interpreter to the workspace by starting an interpreter, this setting no longer applies.

Example

If the preferred default Python interpreter is installed in /opt/python/3.13.0/bin/python, set the default interpreter path as follows:

"python.defaultInterpreterPath": "/opt/python/3.13.0/bin/python"

python.interpreters.include

If Positron Pro’s default discovery strategy isn’t identifying some Python installations on the system, use this setting to specify absolute paths to those additional Python executables or folders containing Python installations to include in interpreter discovery. The specified folders are searched in addition to the default folders for the operating system Positron Pro is running on.

Note

Positron Pro does not display an interpreter if it is included in python.interpreters.include but also excluded in python.interpreters.exclude. If you configure python.interpreters.override, Positron Pro ignores the python.interpreters.include setting.

Tip

When specifying paths to Python interpreters or Python installation directories, ensure that the interpreter executable exists at bin/python within the Python installation directory.

For example, consider a scenario where the Python installation directory is /custom/python/location/3.10.7 and the Python executable is located at /custom/python/location/3.10.7/bin/python.

For Positron Pro to find the interpreter, use one of the following:

  • /custom/python/location,
  • /custom/python/location/3.10.7, or
  • /custom/python/location/3.10.7/bin/python

Additionally, Positron Pro doesn’t detect the interpreter when you specify /custom/python or /custom/python/location/3.10.7/bin.

Example

First, identify the Python installations to include in the available interpreters:

  • /custom/python/location/3.10.7/bin/python
  • /custom/python/location/3.13.0/bin/python
  • /another/custom/python/3.12.0/bin/python

Then, configure the paths as follows:

"python.interpreters.include": [
    "/custom/python/location",
    "/another/custom/python/3.12.0/bin/python"
]

During Python interpreter discovery, Positron Pro will search /custom/python/location and look for /another/custom/python/3.12.0/bin/python in addition to the default locations for Python installations.

python.interpreters.exclude

If Positron Pro displays Python interpreters that shouldn’t be available for users, this setting excludes them from Positron Pro. Specify the absolute paths to the Python executables or folders containing Python installations to exclude.

Note

Positron Pro does not display an interpreter if it is included in python.interpreters.include but also excluded in python.interpreters.exclude. If you configure python.interpreters.override, Positron Pro ignores the python.interpreters.exclude setting.

Example

First, identify the Python installations to exclude from the available interpreters:

  • /custom/python/location/3.10.7/bin/python
  • any Python interpreters within /another/python/location

Then, configure the paths as follows:

"python.interpreters.exclude": [
    "/custom/python/location/3.10.7/bin/python",
    "/another/python/location"
]

When displaying the list of available interpreters, Positron Pro will exclude the Python interpreter /custom/python/location/3.10.7/bin/python and any Python interpreters within /another/python/location.

python.interpreters.override

To limit the Python installations displayed in Positron Pro to a specific set of interpreters, use this setting to specify the only Python installations to include. Specify the absolute paths to Python executables or folders containing Python installations to override the list of the available Python installations.

Note

This setting takes precedence over the python.interpreters.include and python.interpreters.exclude settings.

Tip

When specifying paths to Python interpreters or Python installation directories, ensure that the interpreter executable exists at bin/python within the Python installation directory.

For example, consider a scenario where the Python installation directory is /custom/python/location/3.10.7 and the Python executable is located at /custom/python/location/3.10.7/bin/python.

For Positron Pro to find the interpreter, use one of the following:

  • /custom/python/location,
  • /custom/python/location/3.10.7, or
  • /custom/python/location/3.10.7/bin/python

Additionally, Positron Pro doesn’t detect the interpreter when you specify /custom/python or /custom/python/location/3.10.7/bin.

Example

First, review which Python installations are installed on the system. In this example, the following Python installations are available:

  • /opt/python/3.10.7/bin/python
  • /custom/python/location/3.13.0/bin/python
  • /custom/python/location/3.12.0/bin/python

Then, determine the exclusive list of Python installations to include as available interpreters.

  • /custom/python/location/3.13.0/bin/python

Finally, configure the paths as follows to include the Python interpreter at /custom/python/location/3.13.0/bin/python and not any others:

"python.interpreters.override": [
    "/custom/python/location/3.13.0/bin/python"
]

Positron Pro will only display the Python interpreter at /custom/python/location/3.13.0/bin/python in the interpreter selection UI.

Python Environment Providers

python.environmentProviders.enable

To enable or disable Python environment providers, such as Venv and Conda, use this setting to specify which providers are enabled. By default, all supported environment providers are enabled.

Example

To disable the Conda environment provider and enable the Venv environment provider, set the following configuration:

"python.environmentProviders.enable": {
    "Conda": false,
    "Venv": true
}

R Interpreter Settings

These settings configure which R interpreters are available in Positron Pro. Use these settings to specify the default R interpreter, include additional R installations, exclude specific R installations, and override the list of available R installations.

positron.r.interpreters.default

This setting specifies the absolute path to an R interpreter, highlighting it as the default for new workspaces and prioritizing it in the Positron Pro interpreter selection UI.

Once a user affiliates an R interpreter to the workspace by starting an interpreter, this setting no longer applies.

Example

If the preferred default R interpreter is installed in /opt/R/4.2.0/bin/R, set the default interpreter path as follows:

"positron.r.interpreters.default": "/opt/R/4.2.0/bin/R"

positron.r.customBinaries

If Positron Pro’s default discovery strategy isn’t identifying some R installations on the system, use this setting to specify absolute paths to those additional R binaries to include in interpreter discovery.

To learn more about Positron Pro’s R discovery strategy, refer to Positron’s Discovering R Installations guide.

Note

Positron Pro does not display an interpreter if it is included in positron.r.customRootFolders or positron.r.customBinaries but also excluded in positron.r.interpreters.exclude. If you configure positron.r.interpreters.override, Positron Pro ignores the positron.r.customRootFolders and positron.r.customBinaries settings.

Example

If the following R binaries should be included in the available interpreters:

  • /custom/R/location/4.2.0/bin/R
  • /another/custom/R/4.3.0/bin/R

configure the custom binaries as follows:

"positron.r.customBinaries": [
    "/custom/R/location/4.2.0/bin/R",
    "/another/custom/R/4.3.0/bin/R"
]

positron.r.customRootFolders

If Positron Pro’s default discovery strategy isn’t identifying some R installations on the system, use this setting to specify additional folders to search for those R installations. The specified folders are searched in addition to the default folders for the operating system Positron Pro is running on.

To learn more about Positron Pro’s R discovery strategy, refer to Positron’s Discovering R Installations guide.

Note

Positron Pro does not display an interpreter if it is included in positron.r.customRootFolders or positron.r.customBinaries but also excluded in positron.r.interpreters.exclude. If you configure positron.r.interpreters.override, Positron Pro ignores the positron.r.customRootFolders and positron.r.customBinaries settings.

Tip

When specifying paths to R installation directories, ensure that the interpreter executable exists at bin/R within the R installation directory on Linux-based systems.

For example, consider a scenario where the R installation directory is /custom/R/location/4.2.0 and the R binary is located at /custom/R/location/4.2.0/bin/R.

In order for Positron Pro to find the interpreter, the folder containing the installation directory must be specified: /custom/R/location.

Specifying /custom/R or /custom/R/location/4.2.0/bin will not result in the interpreter being discovered.

Example

If the following R installations should be included in the available interpreters:

  • /custom/R/location/4.2.0/bin/R
  • /custom/R/location/4.1.0/bin/R
  • /another/custom/R/4.3.0/bin/R

configure the custom root folders as follows:

"positron.r.customRootFolders": [
    "/custom/R/location",
    "/another/custom/R"
]

positron.r.interpreters.exclude

If Positron Pro is showing R interpreters that shouldn’t be available for users, use this setting to exclude them from Positron Pro. Specify the absolute paths to the R binaries or folders containing R installations to exclude.

Note

Positron Pro does not display an interpreter if it is included in positron.r.customRootFolders or positron.r.customBinaries but also excluded in positron.r.interpreters.exclude. If you configure positron.r.interpreters.override, Positron Pro ignores the positron.r.interpreters.exclude setting.

Example

If the following R installations should be excluded from the available interpreters:

  • /opt/R/4.2.0/bin/R
  • any R interpreters within /custom/R/location

configure the exclude paths as follows:

"positron.r.interpreters.exclude": [
    "/opt/R/4.2.0/bin/R",
    "/custom/R/location"
]

positron.r.interpreters.override

To limit the R installations displayed in Positron Pro to a specific set of interpreters, use this setting to specify the only R installations to include. Specify the absolute paths to R binaries or folders containing R installations to override the list of the available R installations.

Note

This setting takes precedence over the positron.r.customBinaries, positron.r.customRootFolders, and positron.r.interpreters.exclude settings.

Tip

When specifying paths to R installation directories, ensure that the interpreter executable exists at bin/R within the R installation directory on Linux-based systems.

For example, consider a scenario where the R installation directory is /custom/R/location/4.2.0 and the R binary is located at /custom/R/location/4.2.0/bin/R.

In order for Positron Pro to find the interpreter, one of the following should be used:

  • /custom/R/location,
  • /custom/R/location/4.2.0, or
  • /custom/R/location/4.2.0/bin/R

Specifying /custom/R or /custom/R/location/4.2.0/bin will not result in the interpreter being discovered.

Example

If the following R installations are available:

  • /opt/R/4.2.0/bin/R
  • /custom/R/location/4.3.0/bin/R
  • /custom/R/location/4.1.0/bin/R

configure the override paths as follows to include the R interpreter at /custom/R/location/4.3.0/bin/R and not any others:

"positron.r.interpreters.override": [
    "/custom/R/location/4.3.0/bin/R"
]
Back to top