We are thrilled to announce rig 0.11.0 (and 0.10.0), with lots of new functionalities: user mode R installations, R package and project management and much more. This is the third of three blog posts about the new rig release. This post is about managing R projects.

The first post covered user mode R installations, the second focused on R packages.

Full changelog on the rig web site.

Introduction

The new rig proj command lets you manage R projects and virtual environments. An R project lets you share and run R code in a standardized way. rig’s R projects use an rproj.toml manifest, which is still under development.

rig’s R project implementation largely works the same way as other project management tools for Python, Rust, and other languages.

The project lifecycle

A project lifecycle typically involves

1. rig proj init (or rig proj import) to create a new project.
2. rig proj add (and rig proj remove) to manage project dependencies.
3. rig proj lock to resolve how the project is installed over a range of R versions in a range of platforms.
4. rig proj sync to install a project according to the lock file.
5. rig run to execute R code within the context of the project.

Creating projects

There are three ways to create an R project. One is to create a brand new project with rig proj init. This creates a minimal rproj.toml manifest file that you can either edit manually or via rig proj add:

❯ rig proj init
✓ Created rproj.toml
✓ Created .Renviron
✓ Created .gitignore
✓ Created .rvenvlib/rvenv
ℹ Project set up for R 4.6.1. Next: add dependencies to rproj.toml, then
  run `rig proj lock` and `rig proj sync`.

❯ cat rproj.toml
[project]
name = "x"
version = "0.1.0"
type = "project"

[dependencies]
R = ">= 4.6"

Another way is to convert an existing project to an rproj.toml manifest. Start with an existing R project with a DESCRIPTION file and run rig proj import to create an rproj.toml manifest from it. Or start with an renv lock file and call rig proj renv import. rig proj import keeps all fields of DESCRIPTION, including various types of dependencies. For R packages you can use rproj.toml as the source of truth for package metadata and dependencies and (re)generate DESCRIPTION from it as needed, e.g. for CRAN submission.

A third way to create a project is to write an rproj.toml manifest manually.

Project types

There are two types of R manifests: projects and packages. In general we use project as a generic name for both types and consider a package as a specialized project.

For a package, create the R/, src/, etc. directories as usual. See below for a possible way to use the devtools based development tools for a rig project.

For projects rig does not have a suggested way for organizing R and other code, documentation and tests. If in doubt, follow the conventions of R packages. Use [[bin]] to specify executable scripts within the project, relative to the project root. You’ll be able to run these scripts with rig run.

Locking a project

rig proj lock reads rproj.toml and works out which exact packages should be downloaded and installed to satisfy all requirements from rproj.toml. All requirements always include the optional and soft dependencies. The result is a lock file called rproj.lock. This is also a TOML file, typically much bigger than the original rproj.toml project manifest.

Universal lock files

The lock can and usually does include packages for multiple platforms. The exact set of platforms and R versions to include in the lock file can be specified in rproj.toml or at the command line. By default rig includes the current R release and five platforms: the platform of the current machine, macOS arm64, Windows x86_64, generic glibc Linux and source (four platforms if the current platform coincides with one of the others).

A multi-platform lock file means that it is much easier to plan the cross-platform deployment of a project: a team can include all relevant platforms and R versions in the lock file and commit a lock file to version control.

rig also records system requirements in the lock file, for platforms that need them.

Stable URLs

Universal lock files only really work well if they contain stable URLs for binary packages for all platforms and R versions. This is why it is important to use P3M (or another Posit Package Manager instance) with extended metadata about all older package versions and all their corresponding binary builds. With P3M rig is typically able to generate lock files with binary packages for the last 3-4 R versions on all common platforms.

Sticky lock files

Adding new dependencies to a project runs rig proj lock, but it keeps the package versions already in rproj.lock, unless they conflict with the new requirements. This is important to be able to maintain a stable set of package versions while still adding new dependencies. To update an already existing dependency to a newer version, you need to run rig proj lock --upgrade-package. Or run rig proj lock --upgrade to upgrade all packages.

Preferring binary packages

By default rig does not choose an older binary package over a newer source package. You can change that with the prefer-binary setting in rproj.toml. E.g. prefer-binary = true means that rig will choose an older binary package over a newer source package, if the older package also satisfies the dependency requirements.

Excluding newer package versions

You can prevent rig from automatically upgrading to newer package versions by using the exclude-newer setting in rproj.toml. For example, exclude-newer = "2026-09-30" will exclude any package versions that were published after the specified date. This works for P3M’s CRAN and Bioconductor repositories, but not for generic CRAN-like repositories which typically do not have release dates.

Repositories

Projects ignore the global repository settings configured via rig repos. By default projects use P3M’s CRAN and Bioconductor repositories. This can be configured with [[repository]] entries in rproj.toml. You can turn off P3M’s CRAN and Bioconductor repositories and you can also add your own custom repositories.

rig’s solver and universal lock files work best with P3M’s CRAN and Bioconductor metadata, so we strongly recommend using them whenever possible.

Syncing a project

rig proj sync installs the packages listed in rproj.lock into the project library in .rvenv/lib, inside the project’s virtual environment. It locks first if the project manifest has changed since creating the lock file.

If the current project is a package (type = "package"), then rig proj sync will also install the package itself into the project library.

rig proj sync also installs the R version requested in the lock file, if it is not already installed. This makes it very easy to deploy a project in an empty container or virtual machine: only rig and the lock file are needed and rig installs everything required for the project: R, system requirements and R packages.

rig proj sync installs the hard requirements and the dev dependency group by default. For a production deployment you can use the --no-dev option to skip installing development dependencies. Use --group and --extra to install optional dependency groups and extra dependencies.

Fast and lean libraries

rig clones the package files when installing packages into the project library, whenever possible. This means that installation is very fast and space-efficient. Having the same package version installed for ten projects on the same disk only takes up the space of a single copy.

The virtual environment

A rig project has two kinds of files. rig proj init creates the ones that belong in version control: rproj.toml, .Renviron, .rvenvlib/rvenv and .gitignore. Commit these, together with rproj.lock, and a fresh clone of the project works after a rig proj sync, or right away with rig run.

rig proj sync creates the rest in the .rvenv directory: the project library in .rvenv/lib, R and Rscript wrapper scripts in .rvenv/bin, and some configuration files. .rvenv is specific to the machine, it is in .gitignore, and you can delete it any time, rig proj sync creates it again.

The .Renviron file and the small rvenv package in .rvenvlib make sure that R uses the project library whenever it starts in the project directory: from a terminal, or from RStudio, Positron or VS Code. You do not need to activate the project explicitly, although .rvenv/bin has activation scripts for the common shells if you prefer that.

Inside the project R only sees the project library, the tools library (see below) and the packages that come with R. Packages from your user or site library do not leak into the project.

If the project library is out of date compared to rproj.lock, e.g. after a git pull, R prints a warning at startup, and rig proj status tells you what changed. If you start R with rig run in the project directory, then it automatically runs rig proj sync as needed. If you use Positron, VS Code, RStudio or another IDE, then R will warn at startup if the virtual environment is out of date and suggest that you run rig proj sync and restart R.

Managing dependencies

R package dependencies are specified in the rproj.toml manifest under three types of tables. The [dependencies] table includes packages that are always installed. These are considered as R packages required for the project. Packages in [dependency-groups.<name>] are groups of development dependencies and they are only installed if requested, except for the dev group which is installed by default. For example, the packages that are needed for building the pkgdown website can go into a [dependency-groups.website] table. dependency-groups is similar to Config/Needs/<name> in DESCRIPTION files of R packages. Dependencies of optional features go into [optional-dependencies.<name>] tables and are only installed if requested. For example, if your package has functions for visualization, but these are not required for the core functionality, you may put them in an [optional-dependencies.viz] table and other packages using yours may opt in to the viz feature. (The infrastructure for depending on optional features in packages is not built yet, and package repositories need to support it as well.)

You can edit the rproj.toml manifest manually to add dependencies or use rig proj commands to do it. rig proj add adds packages to rproj.toml, then updates rproj.lock and installs the new packages into the project library:

❯ rig proj add dplyr cli

❯ cat rproj.toml
[project]
name = "x"
version = "0.1.0"
type = "project"

[dependencies]
R = ">= 4.6"
cli = "*"
dplyr = "*"

Without a version requirement rig adds a package as "*", any version. The exact version is recorded in rproj.lock, so you only need a version requirement if the project really needs a certain version. Version requirements use the same syntax as for rig pkg install, e.g. 'cli@>= 3.6' or 'dplyr@^1.1.0'. rig proj remove removes packages.

Use --dev to add a development dependency, e.g. testthat. These go into the [dependency-groups.dev] table.

Packages from GitHub, GitLab, git repositories, URLs and local paths use the same syntax as rig pkg install, see the second post. Bioconductor or other packages coming from the configured repositories work the same way as CRAN packages. To pin a package to a certain repository, e.g. an R universe, use --with-repos:

❯ rig proj add --with-repos rlib=https://r-lib.r-universe.dev cli

This adds the repository to rproj.toml and pins cli to it:

[dependencies]
cli = { version = "*", repository = "rlib" }

[[repository]]
name = "rlib"
url = "https://r-lib.r-universe.dev"

If rig cannot resolve the new dependencies, e.g. because of a typo in a package name, it restores rproj.toml.

Running a project

rig run starts R in the project’s environment, from anywhere inside the project. It locks and syncs the project first, if needed, so day to day you mostly need rig proj add, rig proj remove and rig run.

rig run script.R runs a script in the project’s environment. Arguments after the script name go to the script, and commandArgs(TRUE) picks them up. Use --no-project to run the script without the project.

A project can give names to its scripts, in [[bin]] tables of rproj.toml:

[[bin]]
name = "report"
path = "scripts/report.R"
description = "Build the report"

Then rig run report --format pdf runs scripts/report.R with the --format pdf arguments, and rig run --list lists all named scripts of the project.

You can also run the .rvenv/bin/R and .rvenv/bin/Rscript wrappers directly, or start R from your IDE in the project directory, see the virtual environment above.

Package development with devtools

To develop an R package as a rig project, use type = "package" in rproj.toml, or run rig proj import on an existing package. rig proj sync then installs the package itself into the project library, and creates DESCRIPTION from rproj.toml (if missing), so R CMD build, R CMD check and other tools keep working.

Development tools like devtools, usethis and roxygen2 are not dependencies of the package, so they should not be in rproj.toml. rig has a special global package library for them, called tools, and adds it to the library path of every project. Install your tools there once:

❯ rig pkg install -l tools devtools usethis roxygen2

and then they are available in all projects:

❯ rig run
> devtools::load_all()
> devtools::document()
> devtools::test()

Packages that the package’s tests and documentation need, e.g. testthat or knitr, are different. Add these with rig proj add --dev, so they are locked together with the other dependencies.

Inline scripts

Sometimes a project is just a single R script. For these rig supports inline dependencies: the script declares the R version and the packages it needs in a special comment block with a # /// script header and a # /// footer:

# /// script
# [dependencies]
# R = ">= 4.4"
# cli = "*"
# dplyr = ">= 1.1"
# ///

library(dplyr)
cli::cli_text("Hello from {.pkg cli}!")

Without the leading # characters, the block is the same TOML as in rproj.toml.

rig run script.R installs the right R version if needed, installs the packages into a separate environment in rig’s cache, and then runs the script. Your own package libraries do not change. The next run reuses the environment, so it starts right away. You can share a single .R file, and it runs the same way on every machine that has rig.

You can write the block by hand, or let rig manage it:

❯ rig proj init --script script.R
❯ rig proj add --script script.R cli dplyr
❯ rig proj remove --script script.R dplyr

To pin the exact R and package versions, lock the script:

❯ rig proj lock --script script.R

This writes script.R.lock next to the script. Keep the two files together, and rig run will use the versions from the lock file.

On macOS and Linux, start the script with #!/usr/bin/env -S rig run and make it executable, to run it like any other command. On Windows, rig system script-assoc lets you run .R files from cmd and PowerShell. See the scripts guide for more.

Caches

rig caches the files it downloads: repository metadata, package files, packages it built from source, git repositories of git and GitHub dependencies, and the environments of inline scripts. rig pkg, rig proj and rig run share the same cache, and so do all projects, so rig downloads or builds a package only once. rig refreshes the repository metadata once a day by default.

rig cache info shows how much space the cache takes, by category, and rig cache clean deletes it, or only one category of it, with --category:

❯ rig cache info
❯ rig cache clean --category scripts

Use --no-cache to skip the cache for a single command, and rig system dirs --cache to see where the cache is.

Your feedback is welcome!

We would love to hear your thoughts, suggestions, and any issues you encounter while using rig. Please use the issue tracker for bug reports and feature requests, and the discussion forum or Posit community for general questions and discussions.

Welcome back to another edition of our monthly Positron updates! Each month we share highlights from our latest release and useful resources. Last release we told you about a redesigned welcome page, a first version of Import Data, new Posit Assistant features, expanded Data Connections, package vulnerability scanning, and a more responsive Console. This milestone brings a new ability for Posit Assistant to drive Positron itself, a built-in MCP server so you can bring your own coding agent, Data Connections on by default, faster language features for Quarto, and smoother interpreter and project setup.

Posit Assistant can drive Positron

Posit Assistant can now operate Positron itself, not just the R or Python session inside it. You can ask it to run a Shiny app, open a Parquet file in the Data Explorer, set up a Python environment, browse your data connections, or deploy to Posit Connect. Posit Assistant uses the same source of truth as the Positron UI, so it works with your real interpreters, packages, and connections rather than guessing at them.

In practice, this means Posit Assistant can run and preview Dash, FastAPI, Flask, Gradio, marimo, Streamlit, and Shiny apps with the same app commands you use, see which apps are running along with their status and URL, and stop them. It can show HTML files and URLs in the Viewer pane, and it can read, take screenshots of, and interact with data apps and other content there, which makes it much more useful for checking its own work on an app. It can read your configured and detected Data Connections, browse a connection’s schema, and give you the code to open it. It can also tell which interpreter a project uses, explain why an installed interpreter isn’t showing up, and make that interpreter available, and it knows the commands for deploying to Connect through Posit Publisher.

To try this preview feature, enable the assistant.previewFeatures setting, and tell us what you think in the GitHub discussion.

Bring your own coding agent

If you already have a favorite coding agent other than Posit Assistant, this release lets it work alongside you in Positron. A new built-in Model Context Protocol (MCP) server lets coding agents such as Claude Code, Codex, and Gemini CLI work in your live Python and R sessions. Our goal is to give these agents a set of tools comparable to what Posit Assistant has: agents can list your sessions, run code in the Console, inspect objects without cluttering your history, read recent session history, interrupt a long-running computation, look at the current plot, and search for and run Positron commands. These other agents may not have the data science expertise that Posit Assistant has, but they can still help you write code and explore data.

You stay in the loop on what an agent does. Code that an agent runs shows up in the Console with the agent’s name next to it, so you can always tell agent code from your own. Console tabs also now show a dot when code runs in a console you aren’t looking at, whether that code came from Posit Assistant or an external agent.

To try this experimental feature, enable the ai.mcp.enabled setting. Positron configures Claude Code for you automatically, and the Positron MCP: Add to Coding Agent command sets up the Codex and Gemini CLIs. For any other MCP client, Copy Connection Details gives you a URL and token to connect with.

Data Connections on by default

Data Connections is now the default way to work with databases and data warehouses in Positron. Data Connections connects to databases directly, without needing a Python or R session, and it replaces both the older Connections pane and the Catalog Explorer. If you need the older Connections pane, set dataConnections.enabled to false and reload the window.

This release also extends what you can connect to and how you sign in. Amazon Redshift connections can sign in with AWS Identity and Access Management (IAM), for both Redshift Serverless and provisioned clusters, using credentials from the standard AWS credential provider chain. On Posit Workbench, Snowflake and Databricks connections can use the session’s managed credentials with no credential input at all. Snowflake users get the most new features this month; the Data Connections pane shows Snowflake semantic views with their dimensions, facts, metrics, and relationships, you can browse Snowflake stages as folders and files, and connections in connections.toml show up automatically as detected connections.

Smaller improvements round out the experience. When you open a DuckDB or SQLite file from the Explorer, Positron offers to create a data connection for it. Connect With can now generate ggsql code for SQLite, DuckDB, ODBC, PostgreSQL, and Redshift connections.

The Add Data Connection dialog lists each driver with a short description, and Positron now tells you when a connection fails to open or expand. For slow tables and views, the Data Explorer now shows a progress indicator and placeholders while data arrives, and it loads column summaries in two passes so that missing-value counts appear quickly and sparklines follow later.

Faster language features for Quarto

Positron now provides completions, hover, diagnostics, outline, formatting, and other language features natively for R and Python cells in Quarto and R Markdown documents. Before, the Quarto extension wrote temporary virtual documents to disk to power these features. Positron now uses a virtual notebook in memory instead, which is faster (especially in remote sessions) and solves a whole category of bugs, such as Python imports that did not resolve correctly. It also means Go to Definition, Find References, and Rename work across R cells, finding names that earlier cells define.

The document outline for Quarto and R Markdown documents with many code chunks now updates quickly, and it no longer shows duplicate groups or symbols. Inline output, including HTML tables and the inline Data Explorer, now scales with your editor font size. If you run into problems with the new language features and need to go back to the old behavior, set quarto.embeddedLanguageFeatures.native to false.

Interpreter project setup

Positron is better at setting up the right Python environment for your project. When a workspace has a uv.lock or pixi.lock file but no environment yet, Positron offers to create it with uv sync or pixi install, which is especially handy right after you clone a project. If uv is missing, the New Folder flow can install it for you, and package installs and the Packages pane work with uv right away. When Positron finds a new Python environment in a workspace, it now offers to start a console session in it, and system Python installations now show last in the interpreter picker, below uv, venv, conda, and pyenv environments.

For more control over interpreters in both Python and R, interpreter path settings now support ${workspaceFolder}, so a project can point to an interpreter that lives inside it. The new interpreters.definitions setting lets you define additional R and Python interpreters, each with its own label, environment variables, and startup script. This is useful for workflows like loading environment modules or configuring rJava before a session starts. Set interpreters.discovery to definitionsOnly to show only the interpreters you have defined for a language.

What’s coming next

• Meet Posit at Snowflake World Tour NYC on October 15. Stop by our booth, schedule time with a Posit expert, or catch our theater session on AI-powered data science where your data lives, inside Snowflake.
• Join us at Data Outpost on November 4-5 in San Francisco. I’ll be speaking on “The SQL Agent Harness We Didn’t Mean to Build,” about how the SQL tools we built in Positron for people turned out to already be a harness for AI assistants.

We are thrilled to announce rig 0.11.0 (and 0.10.0), with lots of new functionalities: user mode R installations, R package and project management and much more. This is the second of three blog posts about the new rig release. This post is about managing R packages.

The first post covered user mode R installations. The third post focuses on project management.

Full changelog on the rig web site.

Introduction

The new rig pkg command lets you manage R packages: installing, removing, and querying package dependencies. It supports CRAN-like repositories, packages in git repositories (including on GitHub), URLs pointing to package files and packages in local files and directories.

rig pkg is aimed at R users and developers who use a single (or a few) package libraries. If you prefer to use project-specific libraries, you probably want to use rig proj instead.

Managing installed packages

rig pkg list lists installed packages in a library. rig pkg remove removes a package from a library.

❯ rig pkg list
559 packages (R 4.6.1, main: /Users/gaborcsardi/Library/R/arm64/4.6/library)

Package              Version      Built   Platform                   Source
----------------------------------------------------------------------------------------------------------------
abind                1.4-8        4.6.0   -                          RSPM
ade4                 1.7-24       4.6.0   aarch64-apple-darwin23     CRAN
adegenet             2.1.11       4.6.0   aarch64-apple-darwin23     CRAN
AdmixPoly            1.0.1        4.6.0   aarch64-apple-darwin20     RSPM
affy                 1.90.0       4.6.1   aarch64-apple-darwin23     RSPM
affyio               1.82.0       4.6.0   aarch64-apple-darwin20     RSPM
[...]

rig pkg commands use the current default R version (as in rig default), unless the -r or --r-version option specifies otherwise. They use the default library (as in rig library default), unless the -l or --library option specifies otherwise.

rig pkg doctor checks the health of your package library, identifying any issues with installed packages or their dependencies: missing dependencies, dependency conflicts, ABI conflicts, etc. It also tells you how to fix these issues.

❯ rig pkg doctor
3 problems (1 error, 2 warnings) in 559 packages (R 4.6.1, main: /Users/gaborcsardi/Library/R/arm64/4.6/library)

Package              Version   Severity   Problem   Details
-------------------------------------------------------------------------------------------------------------
00LOCK-dress.graph   -         warning    lock      lock directory left behind by an interrupted installation
dress.graph          -         warning    broken    no DESCRIPTION file
missoNet             1.5.1     error      missing   Imports ComplexHeatmap, not installed

To fix the errors, run:
  rig pkg install ComplexHeatmap

To remove the leftover lock directories, if no installation is running, run:
  rm -rf /Users/gaborcsardi/Library/R/arm64/4.6/library/00LOCK-dress.graph

To remove the broken packages, run:
  rm -rf /Users/gaborcsardi/Library/R/arm64/4.6/library/dress.graph

✗ Found 1 error in /Users/gaborcsardi/Library/R/arm64/4.6/library

Installing packages

rig pkg install can install R packages from CRAN-like repositories, git repositories, GitHub, URLs, and local paths. It uses the default R version and the default package library (see below about libraries), unless otherwise specified. It caches metadata and package files heavily, avoids redundant downloads and installations, and performs downloads and package builds in parallel. It uses the host OS’s file cloning capabilities to efficiently copy files when installing packages.

If you used the pak R package to install R packages previously, rig pkg will probably feel familiar, except that you can run it from the command line instead of from within R.

This is what installing a package into an empty library looks like, if the package files are already cached:

❯ rig pkg install dplyr
▶ Downloading binary package metadata
▶ Solving dependencies
✓ Solved dependencies
15 of 15 packages to install (R 4.6.1, test: /Users/gaborcsardi/Library/R/arm64/4.6/library/__test)
Package     Version  Type    Action   Reason
cli         3.6.6    binary  install  not installed
dplyr       1.2.1    binary  install  not installed
generics    0.1.4    binary  install  not installed
glue        1.8.1    binary  install  not installed
lifecycle   1.0.5    binary  install  not installed
magrittr    2.0.5    binary  install  not installed
pillar      1.11.1   binary  install  not installed
pkgconfig   2.0.3    binary  install  not installed
R6          2.6.1    binary  install  not installed
rlang       1.3.0    binary  install  not installed
tibble      3.3.1    binary  install  not installed
tidyselect  1.2.1    binary  install  not installed
utf8        1.2.6    binary  install  not installed
vctrs       0.7.3    binary  install  not installed
withr       3.0.3    binary  install  not installed

▶ Downloading 15 packages
✓ Cached: cli
✓ Cached: dplyr
✓ Cached: generics
✓ Cached: glue
✓ Cached: lifecycle
✓ Cached: magrittr
✓ Cached: pillar
✓ Cached: pkgconfig
✓ Cached: R6
✓ Cached: rlang
✓ Cached: tibble
✓ Cached: tidyselect
✓ Cached: utf8
✓ Cached: vctrs
✓ Cached: withr
Complete: 0 downloaded, 15 cached [========================================] 15/15 packages

▶ Installing 15 packages.
Installed R6 2.6.1
Installed cli 3.6.6
Installed rlang 1.3.0
Installed magrittr 2.0.5
Installed pkgconfig 2.0.3
Installed glue 1.8.1
Installed withr 3.0.3
Installed utf8 1.2.6
Installed generics 0.1.4
Installed lifecycle 1.0.5
Installed vctrs 0.7.3
Installed tidyselect 1.2.1
Installed pillar 1.11.1
Installed tibble 3.3.1
Installed dplyr 1.2.1
✓ Installed all 15 packages successfully
✓ Installed 15 packages (R 4.6.1, test: /Users/gaborcsardi/Library/R/arm64/4.6/library/__test)

Version constraints

rig pkg install supports version constraints for packages. Request a specific version of a package with @==<version>:

❯ rig pkg install ggplot2@==4.0.2

If you are familiar with ~ and ^ version constraints from other languages, you can use them with rig pkg install as well. E.g. to install the latest version of the ggplot2 3.x.y series, you would run:

❯ rig pkg install ggplot2@^3.0.0

Dependency solver

The rig dependency solver makes sure that all package dependencies are resolved correctly before installation. If the combination of packages cannot be installed on the specified R version or platform, rig will report an error and refuse to proceed with the installation. For example:

❯ rig pkg install -r 4.0.5-x86_64 'testthat@>=3.3.0'
▶ Downloading binary package metadata
▶ Solving dependencies
✗ Cannot resolve dependencies for R 4.0.5 / x86_64-apple-darwin:
  Because testthat >=3.3.0 depends on R >=4.1.0 and you requested
  testthat >=3.3.0, the requested packages cannot be installed.

Packages from git, GitHub, URLs, paths

If you are familiar with pak’s syntax for installing packages from various non-CRAN sources, you can use the same syntax with rig. E.g. a GitHub package is simply username/repo. You can use the usual syntax for tags, branches, pull requests:

❯ rig pkg install r-lib/cli
❯ rig pkg install r-lib/cli@badcafe
❯ rig pkg install r-lib/cli@some-branch
❯ rig pkg install r-lib/cli#41

Prefix packages in git repositories with git::. To install a package from a URL simply use the full URL. For a local path use a relative path starting with ./, ../ or ~/ or an absolute path:

❯ rig pkg install .
❯ rig pkg install ./mypkg
❯ rig pkg install ../mypkg
❯ rig pkg install ~/works/mypkg
❯ rig pkg install /opt/src/mypkg
❯ rig pkg install ./mypkg_1.0.0.tar.gz

Preferring binary packages

rig prefers to install the binary package for a certain package version if it is available, instead of building and potentially compiling it from source. By default it does not choose an older version over a newer one just because a binary is available for the older version. The --prefer-binary option changes this. Use it if you prefer older binary packages over newer source packages:

❯ rig pkg install --prefer-binary tidyverse

Installing dependencies

To install the dependencies of a package, without installing the package itself, use --no-install-project. This is especially useful to install all dependencies of a package tree in the current working directory. The second variant also installs soft (development) dependencies:

❯ rig pkg install --no-install-project .
❯ rig pkg install --no-install-project --dev .

Repositories

rig pkg subcommands always use the configured repositories, see the rig repos command. They also have --with-repos and --without-repos options to include or exclude specific repositories when performing a single package operation, without modifying the configured repositories. E.g. to query the version of a package on CRAN and P3M you can run:

❯ rig pkg info otel --without-repos --with-repos=p3m --versions
otel — 2 versions (latest 0.2.0)

Version   Published    R          Deps
-------------------------------------------------------
0.1.0     2025-07-31   >= 3.6.0      0
0.2.0     2025-08-29   >= 3.6.0      0   ← latest

❯ rig pkg info otel --without-repos --with-repos=cran --versions
otel — 1 version (latest 0.2.0)

Version   Published   R          Deps
-------------------------------------------------------
0.2.0     ?           >= 3.6.0      0   ← latest

Package queries

rig pkg info prints information about a package, by default about the latest version:

❯ rig pkg info tidymodels
tidymodels 1.5.0 (RSPM)
Easily Install and Load the 'Tidymodels' Packages

The tidy modeling "verse" is a collection of packages for modeling and
statistical analysis that share the underlying design philosophy, grammar, and
data structures of the tidyverse.

Maintainer    Max Kuhn <max@posit.co>
License       MIT + file LICENSE
Published     2026-04-23 06:20:02 UTC
URL           https://tidymodels.tidymodels.org,
              https://github.com/tidymodels/tidymodels
BugReports    https://github.com/tidymodels/tidymodels/issues
Compilation   no

Depends       R (>= 4.1)
Imports       broom (>= 1.0.12), cli (>= 3.6.6), conflicted (>= 1.2.0), dials
              (>= 1.4.3), dplyr (>= 1.2.1), ggplot2 (>= 4.0.3), hardhat (>=
              1.4.3), infer (>= 1.1.0), modeldata (>= 1.5.1), parsnip (>=
              1.5.0), purrr (>= 1.2.2), recipes (>= 1.3.2), rlang (>= 1.2.0),
              rsample (>= 1.3.2), rstudioapi (>= 0.18.0), tailor (>= 0.1.0),
              tidyr (>= 1.3.2), tune (>= 2.1.0), workflows (>= 1.3.0),
              workflowsets (>= 1.1.1), yardstick (>= 1.4.0)
Suggests      covr, glue, knitr, rmarkdown, testthat (>= 3.0.0), xml2

rig pkg info --versions lists all versions of a package. This only works with P3M repositories because it needs extended metadata that plain CRAN-like repositories typically do not have:

❯ rig pkg info tidymodels --versions
tidymodels — 17 versions (latest 1.5.0)

Version   Published    R        Deps
-------------------------------------------------------
0.0.1     2018-07-27   >= 3.1     18
0.0.2     2018-11-27   >= 3.1     20
0.0.3     2019-10-04   >= 3.1     20
0.1.0     2020-02-16   >= 3.1     22
0.1.1     2020-07-14   >= 3.1     20
0.1.2     2020-11-22   >= 3.1     19
0.1.3     2021-04-19   >= 3.1     20
0.1.4     2021-10-01   >= 3.1     21
0.2.0     2022-03-19   >= 3.4     21
1.0.0     2022-07-13   >= 3.4     21
1.1.0     2023-05-01   >= 3.4     21
1.1.1     2023-08-24   >= 3.4     21
1.2.0     2024-03-25   >= 3.6     21
1.3.0     2025-02-21   >= 3.6     21
1.4.0     2025-09-05   >= 4.1     21
1.4.1     2025-09-08   >= 4.1     21
1.5.0     2026-04-23   >= 4.1     21   ← latest

rig pkg deps prints the dependencies of a package. rig pkg tree does the same, but as a dependency tree. You can use these commands to query non-CRAN-like packages. E.g. the dependency tree of the package in the current working directory is

❯ rig pkg tree --dev .
otelsdk 0.2.4.9000 (local: /Users/gaborcsardi/works/otelsdk) — 14 direct, 51 total
├── otel 0.2.0
│   └── R (>= 3.6.0) [D]
└── utils
[Suggests]
├── callr 3.8.0
│   ├── R (>= 3.4) [D]
│   ├── otel 0.2.0 (>= 0.2.0) (*)
│   ├── processx 3.9.0 (>= 3.6.1)
│   │   ├── R (>= 3.4.0) [D]
│   │   ├── ps 1.9.3 (>= 1.9.3)
│   │   │   ├── R (>= 3.4) [D]
│   │   │   └── utils
│   │   ├── R6 2.6.1
│   │   │   └── R (>= 3.6) [D]
│   │   └── utils
│   ├── R6 2.6.1 (*)
│   └── utils
├── cli 3.6.6
│   ├── R (>= 3.4) [D]
│   └── utils
├── curl 8.0.0
│   └── R (>= 3.0.0) [D]
[...]

The --dev flag includes development dependencies as well.

rig pkg search searches all CRAN packages using R-hub package search service:

❯ rig pkg search palette --short
- "palette" ----------------------------------- 177 packages in 0.009 seconds -
 #     package      version  by                     @ title
 1 100 RColorBrewer 1.1-3    Erich Neuwirth        5y ColorBrewer Palettes
 2  46 colorspace   2.1-3    Achim Zeileis         3M A Toolbox for Manipula...
 3  23 paletteer    1.7.0    Emil Hvitfeldt        9M Comprehensive Collecti...
 4  16 ggsci        5.2.0    Nan Xiao              2M Scientific Journal and...
 5  13 wesanderson  0.3.7    Karthik Ram           3y A Wes Anderson Palette...
 6   8 rcartocolor  2.1.2    Jakub Nowosad         1y 'CARTOColors' Palettes
 7   8 pals         1.10     Kevin Wright          2y Color Palettes, Colorm...
 8   8 scico        1.5.0    Thomas Lin Pedersen   3y Colour Palettes Based...
 9   6 palette      0.0.3    Christopher T. Kenny  1y Color Scheme Helpers
10   6 MetBrewer    0.2.0    Blake Robert Mills    5y Color Palettes Inspire...
11   6 palr         0.5.0    Michael D. Sumner     2M Colour Palettes for Data
12   6 blends       0.1.2    David Hodge           3M Blend Colours and Pale...
13   6 biscale      1.1.0    Christopher Prener    1y Tools and Palettes for...
14   5 palettes     0.2.2    Michael McCarthy      1y Methods for Colour Vec...
15   5 PrettyCols   1.1.0    Nicola Rennie         2y Pretty Colour Palettes
16   5 gifski       1.32.0-2 Jeroen Ooms           2y Highest Quality GIF En...
17   5 wacolors     0.3.1    Cory McCartan         5y Colorblind-Friendly Pa...
18   4 colourpicker 1.3.0    Dean Attali           3y A Colour Picker Tool f...
19   4 amerika      0.1.1    Philip Waggoner       1y American Politics-Insp...
20   4 makePalette  0.1.2    Jorge L. C. Musaja    3y Make Palette

Next 20 results: rig pkg search palette --from 21 --short

Package libraries

rig creates a user-level package library for each R installation by default. (See the rig FAQ why.) This is the package library that rig pkg commands use by default.

The rig library command supports creating other package libraries, still stored in the user’s home directory. You can refer to them by name and make them the default library for rig pkg commands with rig library default.

For example to create a temporary library and install the Shiny package from GitHub into it, including development dependencies, you can run:

rig library add test
rig library default test
rig pkg install --dev rstudio/shiny

You can also use the -l or --library option of the rig pkg commands to change the package library temporarily for one command, without changing the default.

If you are using the macOS menu bar app, then you can also manage package libraries through the app’s interface.

System requirements

On certain Linux systems rig supports automatic system requirements installation. These are currently:

• Ubuntu Linux
• RedHat Enterprise Linux and clones
• openSUSE Linux and SUSE Linux Enterprise
• Debian Linux
• Fedora Linux
• Alpine Linux

For the automatic system requirements installation to work, rig must run as the root user or with password-less sudo privileges to call the system package manager.

Note that in user mode, rig installs the self-contained manylinux R build, which does not require any system-level dependencies and also sets up Posit’s manylinux package repository, which has self-contained binaries for most CRAN and Bioconductor packages. So in user mode you typically do not need to worry about system-level dependencies.

Your feedback is welcome!

We would love to hear your thoughts, suggestions, and any issues you encounter while using rig. Please use the issue tracker for bug reports and feature requests, and the discussion forum or Posit community for general questions and discussions.

We are thrilled to announce rig 0.11.0 (and 0.10.0), with lots of new functionalities: user mode R installations, R package and project management and much more. This is the first of three blog posts about the new rig release. This post is about managing R installations and the new user mode. The second post shows how rig can help with managing R packages, and the third focuses on project management.

Full changelog on the rig web site.

New Web Site

rig has a new web site at https://rig.r-lib.org! See this web site for installation instructions, including the new user mode install; reference documentation (also in rig help!), guides about larger topics and tutorials to get started.

User Mode R Installations

rig can now install and manage R installations without requiring administrative privileges. rig calls this user mode. In user mode, R installations are installed in the user’s home directory rather than system-wide. System-wide installations are still the default currently, and they are called admin mode.

You may have both user mode and admin mode installations on one computer, but each rig command runs in either user mode or admin mode. The default is admin mode. See below for how to change it. Use --admin or --user to pick the mode for a single command, e.g. rig ls --admin always lists admin mode installations, and rig ls --user always lists user mode ones.

Advantages of using user mode:

• No admin: no need for administrative privileges.
• All Linux: works on all glibc (from glibc 2.34) and musl (from musl 1.2) based Linux systems.
• Multiple patch versions: on macOS you can install multiple patch versions side by side.
• Convenience: no need to use sudo or an admin account to install and manage R.

User mode is quite new, though. It is much less tested than admin mode, and you may encounter bugs or unexpected behavior more frequently. On Linux, the generic distro-agnostic builds may be slower for numerical work than builds specifically compiled for the distribution.

User mode (admin mode as well, actually) is slightly different on each operating system. Here is a table about where rig stores its files on each OS in both modes.

You can call the new rig system dirs command to see where rig stores its various files:

❯ rig system dirs
Mode                  user
Architecture          arm64
R root                /Users/gaborcsardi/.local/share/rig/r
Binary dir            /Users/gaborcsardi/.local/bin
Config file           /Users/gaborcsardi/Library/Application Support/com.gaborcsardi.rig/config.json
Data dir              /Users/gaborcsardi/Library/Application Support/com.gaborcsardi.rig
Cache dir             /Users/gaborcsardi/Library/Caches/com.gaborcsardi.rig
Download dir          /var/folders/h9/6ct_py4s319fxt88dxn506l00000gp/T/rig-502
Logs dir              /Users/gaborcsardi/Library/Logs/com.gaborcsardi.rig
Project library root  (in-project, .rvenv/lib)

The same in admin mode:

❯ rig system dirs --admin
Mode                  admin
Architecture          arm64
R root                /Library/Frameworks/R.framework/Versions
Binary dir            /usr/local/bin
Config file           /Users/gaborcsardi/Library/Application Support/com.gaborcsardi.rig/config.json
Data dir              /Users/gaborcsardi/Library/Application Support/com.gaborcsardi.rig
Cache dir             /Users/gaborcsardi/Library/Caches/com.gaborcsardi.rig
Download dir          /var/folders/h9/6ct_py4s319fxt88dxn506l00000gp/T/rig-502
Logs dir              /Users/gaborcsardi/Library/Logs/com.gaborcsardi.rig
Project library root  (in-project, .rvenv/lib)

macOS

On arm64 macOS rig can install both arm64 and x86_64 builds of R. The latter ones need Rosetta to run. User mode has a different, simpler naming scheme than admin mode on macOS, matching Linux and Windows. This is an example list of user mode R installations:

❯ rig ls
* name          version    aliases
------------------------------------------
  3.6.3-x86_64  (R 3.6.3)
  4.0.5-x86_64  (R 4.0.5)
  4.1.3
  4.1.3-x86_64  (R 4.1.3)
  4.2.3
  4.3.3
  4.4.3
  4.5.3                    oldrel
  4.5.3-x86_64  (R 4.5.3)  oldrel-x86_64
  4.6.0
* 4.6.1                    release
  4.6.1-x86_64  (R 4.6.1)  release-x86_64
  devel         (R 4.7.0)
  devel-x86_64  (R 4.7.0)
  next          (R 4.6.1)
  next-x86_64   (R 4.6.1)

• The native (arm64) builds are named simply with the version number.
• R-devel is simply named devel and the next version of R (R-patched, R-alpha, etc.) is named next.
• The x86_64 builds are suffixed with -x86_64.
• You can use the release alias for the most recent version of R and the oldrel alias for the previous minor release branch. E.g. the R-release quick link starts the latest version of R.

Windows

On Windows rig installs CRAN’s R builds as a regular user in user mode. This installation writes the user’s registry settings instead of the system-wide registry settings.

The names of the R installations are the same as for admin mode. rig now supports installing x86_64 and aarch64 R builds on aarch64 Windows, and similarly to macOS, the non-native builds get a -x86_64 suffix:

PS C:\Users\Gabor Csardi> rig ls
* name          version    aliases
------------------------------------------
  4.4.3
  4.4.3-x86_64  (R 4.4.3)
  4.5.3
* 4.6.1                    release
  devel         (R 4.7.0)
  next          (R 4.6.1)

The new rig rtools command lets you manage Rtools installations. In user mode they are installed into the user’s roaming profile directory, and rig configures R and Rtools to work together correctly. On aarch64 Windows, you can install both x86_64 and aarch64 versions of Rtools.

PS C:\Users\Gabor Csardi> rig rtools ls
name  version  full-version   arch     path
------------------------------------------------------
40    4.0      4.0.3.0        x86_64   C:\Users\Gabor Csardi\AppData\Roaming\rig\data\rtools\40-x86_64
44    4.4      4.4.6459.6401  aarch64  C:\Users\Gabor Csardi\AppData\Roaming\rig\data\rtools\44
45    4.5      4.5.6768.6492  aarch64  C:\Users\Gabor Csardi\AppData\Roaming\rig\data\rtools\45

Linux

On Linux rig installs a portable (manylinux) R build in user mode. These builds are self-contained, generic glibc (or musl) builds of R. These builds are intended to work on a wide range of Linux distributions. However, they are not as battle-tested as the builds rig uses in admin mode.

On glibc systems rig also configures the manylinux repository for CRAN, that pairs very well with the portable R builds. These packages are self-contained and compatible with most glibc-based Linux distributions:

> getOption("repos")
                                                         P3M-manylinux
"https://packagemanager.posit.co/cran/__linux__/manylinux_2_28/latest"
                                                                  CRAN
                                         "https://cloud.r-project.org"

Positron and RStudio configuration

rig automatically configures RStudio (when running rig add and rig default), so that the rig-default R version is also the default in RStudio. On macOS and Windows this is automatic. On Linux rig puts the rig binary directory (see the table above) on the PATH in user mode, and it is generally on the PATH in admin mode. This is enough to ensure that the rig-default R version is also the default in RStudio on Linux.

Positron does not have a generic default R version like RStudio does, but you can choose a default for each workspace. rig (in rig add and rig default) updates your Positron configuration (the current user’s config file) to make sure that Positron finds all user-mode R installations.

Switching to user mode

Call rig system user-mode to switch a previous setup from admin mode to user mode. This will reinstall your current R installations in user mode, and remove the admin mode installation. (But see its options to adjust this!)

See more about the migration at the rig homepage.

Portable Linux

Above you have seen how rig installs portable manylinux builds in user mode. It is also possible to install them in admin mode. This can be useful for Linux systems that rig does not have native builds for. To install a portable Linux build use --platform portable:

rig add --platform portable 4.6

Moreover, if rig does not support a Linux distribution natively, it will install the manylinux (or musllinux) builds instead, assuming that they are supported, even in admin mode. With this, most Linux distributions work automatically, in both admin and user modes.

Repository management

The rig release improved the rig repos subcommand substantially. These are the biggest changes.

P3M by default

rig now configures Posit Public Package Manager (P3M) as a default repository, on all platforms except aarch64 Windows. (Because P3M would serve incompatible x86_64 binaries here.) This is because we found P3M more reliable and because P3M includes older package versions and has more extensive metadata.

Nevertheless you can opt out with rig add --without-repos=p3m ... at installation time, or with rig repos setup --without-repos=p3m at any time.

Custom repositories

You can now add custom repositories to your rig configuration using rig repos add <name> <url>. For example:

rig repos add myrepo https://myrepo.example.com

You can then turn these (and also the built-in) repositories on or off using rig repos enable and rig repos disable.

Improved repository list

The output of rig repos available is now more informative and easier to read. Type rig repos available <reponame> to get more information about a repository.

❯ rig repos available
8 repositories

Name              Default   Type       Title
-----------------------------------------------------------------------------
P3M               depends   built-in   Posit Public Package Manager
P3M-manylinux     depends   built-in   Posit Package Manager manylinux portable packages
RHUB              no        built-in   R-Hub repositories
r-universe/cran   depends   built-in   R-universe CRAN mirror
r-universe/bioc   no        built-in   R-universe Bioconductor mirror
CRAN              yes       built-in   The Comprehensive R Archive Network
CRAN-archive      depends   built-in   CRAN archive
Bioconductor      no        built-in   Open source software for Bioinformatics

Use `rig repos available <name>` to see a repository's URLs.
`depends`: a default only on some platforms, architectures or R versions.

❯ rig repos available r-universe/cran
r-universe/cran (1 URL)
R-universe CRAN mirror

R-universe's mirror of CRAN. The only repository serving arm64 Windows binary
packages.

Default      only on platforms matching aarch64-*-mingw32

URL          https://cran.r-universe.dev
Platforms    windows, *-mingw32
Archs        aarch64

Repository status

Use rig repos status to check the status of all enabled repositories.

❯ rig repos status
6 repositories of R 4.6.1, index bin/macosx/sonoma-arm64/contrib/4.6

name              ping   status        types              updated            url
-----------------------------------------------------------------------------
P3M             601 ms   ok            source, win, mac   -                  https://packagemanager.posit.co/cran/latest
BioCsoft        233 ms   ok            source, win, mac   2026-10-01 17:08   https://bioconductor.org/packages/3.23/bioc
BioCann         120 ms   source only   source, win, mac   2026-08-01 16:49   https://bioconductor.org/packages/3.23/data/annotation
BioCexp         111 ms   source only   source, win, mac   2026-09-15 20:32   https://bioconductor.org/packages/3.23/data/experiment
BioCworkflows   111 ms   source only   source, win, mac   2026-08-01 16:39   https://bioconductor.org/packages/3.23/workflows
BioCbooks       120 ms   source only   source, win, mac   2026-08-01 16:25   https://bioconductor.org/packages/3.23/books

`ping` is the time the repository took to answer for the index above.
`types` is what the R installation's `repositories` file declares.
`source only`: this repository has no index for this platform and R version.

Other improvements

Avoid unneeded reinstalls

rig add now does not reinstall an R version if it is already installed. Use --reinstall to force a reinstall.

.exe quick links on Windows

On Windows rig now uses .exe quick links instead of .bat files. .bat files have a lot of issues with passing arguments, .exe files work much better.

Run R with R on Windows

The new rig system fix-r-alias subcommand deletes the R alias from PowerShell, so you can now use R to start R.

rig is now signed on Windows

Thanks to the SignPath Foundation, the rig executables and the rig installer are all signed now.

rig system blas

The new rig system blas command lets you manage the BLAS/LAPACK library used by R on macOS.

Update and uninstall

Use rig self update to update rig itself, and rig self uninstall to uninstall it. These commands only work if you installed rig using the install script. If you installed it with a package manager or ran the installer manually, you have to use the same package manager or uninstall it manually.

Your feedback is welcome!

We would love to hear your thoughts, suggestions, and any issues you encounter while using rig. Please use the issue tracker for bug reports and feature requests, and the discussion forum or Posit community for general questions and discussions.

Acknowledgments

Huge thanks to everyone who contributed to rig 0.10.0 and 0.11.0: @achubaty, @AdaemmerP, @AdrienLeGuillou, @Adrilihan, @Andryas, @bashirhamidi, @benyamins, @biocyberman, @Bisaloo, @cderv, @CGMossa, @danielloader, @dkczk, @eitsupi, @elendil95, @eliocamp, @EllaKaye, @etiennebacher, @frosforever, @gdevenyi, @ggrothendieck, @grantmcdermott, @gvelasq, @hadley, @jabenninghoff, @jameslairdsmith, @jennybc, @jeroen, @jfin4, @John15321, @jonbry, @JosiahParry, @kalenkovich, @kenahoo, @kieran-mace, @klmr, @krlmlr, @lotum-david-j, @malcolmbarrett, @mcanouil, @mhurtado13, @MilesMcBain, @mitsuki5284, @mns-nordicals, @morphatic, @Nerwosolek, @noamross, @paluigi, @robjhyndman, @rumichaska, @SaintRod, @sammieephung, @sda030, @ShixiangWang, @t-kalinowski, @tylermorganwall, @venpopov, @vikasrawal, @wzbillings, and @zivankaraman.

Welcome back to another edition of our monthly Positron updates! Each month we share highlights from our latest release and useful resources. Last release we told you about new Data Connections sources, a round of polish for inline output in Quarto documents, and help installing missing packages. This milestone brings a redesigned welcome page, a first version of Import Data, new Posit Assistant features, expanded Data Connections, package vulnerability scanning, and a more responsive Console.

Welcome page refresh and interpreter setup

We redesigned the Positron welcome page. It now leads with an environment setup card that checks whether Python and R are ready to use, with actions to help resolve any problem it finds. The Positron badge and name now come with a Help button that opens the Help pane, and a banner links to the walkthroughs, including a new “Get Started with Positron” walkthrough that covers the Positron panes, keyboard shortcuts, built-in extensions, and Git.

The environment setup theme continues into interpreter selection itself. When you select a Python managed by your operating system or a package manager, Positron now offers to create a virtual environment for your workspace instead of installing packages into that shared interpreter. With no folder open, the environment Positron creates now lives at ~/.virtualenvs/positron rather than ~/.venv, so it stays in the interpreter picker after a restart, and Positron asks before creating an environment in your home directory. We also removed the confusing startup notification that reported no interpreters were found while linking to documentation saying no setup was needed, and interpreters installed under /opt/python are now labeled Global instead of Unknown in the interpreter picker.

Import Data

Before we started work this month, importing data via the Positron UI was our most upvoted feature request and this release now delivers a first version. When you view a CSV or TSV file in the Data Explorer, a new Import Data button in the action bar opens a dialog. The dialog shows the code to load that file into a data frame. You can copy the code, or click Import to run it in the console, starting a session if one is not already running.

Import Data supports CSV and TSV files in Python with pandas and in R with the readr package, as well as Excel workbooks and Parquet files (with readxl and nanoparquet in R). The generated code can reproduce the filters and sorts you have applied in the Data Explorer, and it names the file by a workspace-relative path when the file is inside your workspace, so the code is easier to share and rerun. You can open the dialog from the Data Explorer, the File menu, the Variables pane, or the File Explorer context menu.

Posit Assistant

This release brings a new Agent Layout that opens Posit Assistant in the editor area with a compact Session pane, giving you more visibility into the agent’s actions as it works alongside your code. Configuring language model providers also gets a redesign. Our new Configure LLM Providers modal groups providers by connection state, so you can see at a glance which providers are ready to use. If you have trouble with the new dialog and need to switch back, set assistant.newProviderModal to false.

You can now configure multiple custom providers, each with its own name, type, endpoint, credential, and model list; the previous single “Custom Provider” option is now called “OpenAI Compatible” to better match what it actually does. Amazon Bedrock users get a smoother experience as well. An expired AWS SSO session can be renewed right from the provider modal instead of requiring aws sso login in a terminal, and the AWS profile and region can now be set in the configuration dialog rather than only through environment variables or a hand-edited providers.json. Speaking of which, providers.json now accepts comments, and your comments survive edits that Positron makes to the file.

Data Connections

The Data Connections preview keeps growing. A new ODBC data connection driver lets you browse any database with an installed ODBC driver in the Connections pane and open it in the Data Explorer. Data sources already configured on your machine appear automatically. Databricks gains OAuth sign-in on desktop and reads DATABRICKS_TOKEN, DATABRICKS_HOST, and DATABRICKS_CONFIG_FILE credentials managed by Posit Workbench automatically. A Disconnect option in the context menu closes a connection and any Data Explorers opened from it, and each data connection driver now gets its own log output channel.

Smaller improvements round out the preview. You can now set dataConnections.enabled per workspace, so a repository can turn on the Connections pane for anyone who opens it. The tree is shallower so table and column names get more of the panel’s width, and a new dataConnections.tree.indent setting controls the indentation. DuckDB connections now default to read-only, so the Connections pane and a Python or R session can have the same database open at once; when a lock conflict does happen, the error now explains that another session has locked the database.

Package security vulnerabilities

The Packages pane now shows known security vulnerabilities (Common Vulnerabilities and Exposures scoring) for installed Python and R packages, so you can see at a glance whether something in your environment has a known CVE. The data comes from your environment’s own Posit Package Manager repository when it has one, and from the public Posit instance otherwise, so what you see reflects the same package source your organization already governs.

A more responsive Console

Console code submission is now faster, always shows visual feedback, and can be canceled while a completeness check is in flight; the Console no longer waits indefinitely with no feedback when a kernel is slow or unreachable. The Console breaks multi-statement input into complete expressions and executes them statement by statement for languages that support it. A new console.promptWhenIncomplete setting runs submitted code immediately without a completeness check.

A few more Console fixes are worth knowing about. The Console no longer takes focus at runtime startup when you are working in another view or editor, Interrupt stays visible after switching between busy consoles, and session names now ellipsize to fit as the console tab list narrows.

What’s coming next

• posit::conf(2026) is next week! Our team will have several sessions on Positron, and there is still time to register to join us virtually from anywhere in the world.
• Meet Posit at CDAO Government on September 22-23 in Washington, D.C. Stop by our booth to talk data modernization and where agentic AI fits in government.

Welcome back to another edition of our monthly Positron updates! Each month we share highlights from our latest release and useful resources. Last release we told you about several major features that came out of preview to general availability, including the new notebook editor. This milestone we are excited to share new functionality for SQL support, reproducible authoring, helping you know when packages are missing, and more.

Data Connections

Data Connections is our new way to work with SQL and database-like resources in Positron, from local files and database servers to cloud data warehouses. It is currently available as a preview feature, and you can enable it with the dataConnections.enabled setting. This release more than doubles the number of data sources you can reach. Amazon Redshift, Snowflake, Databricks, and Posit Connect pins join the existing DuckDB, PostgreSQL, and SQLite support.

The panel itself is more capable as well. Refresh and Refresh All reload the tree while preserving what you have expanded, briefly highlighting the rows that were reloaded. Open connections now show an indicator. Collapsing a connection in the UI keeps you connected to your data source, while anything you’ve previewed with the Data Explorer stays still open. When you remove a connection, Positron asks for confirmation and reports how many Data Explorers will close with it.

Data Connections is still an experimental preview, and your feedback continues to shape it. Tell us which databases and warehouses you need, and anything confusing, missing, or broken, in the Data Connections discussion.

Inline output for Quarto

Inline output for .qmd documents came out of preview last release, and this release brings you a substantial round of polish for this way of working. Be aware that the Quarto settings have moved into a dedicated quarto.* namespace with its own group in the Settings editor. The previous positron.quarto.* keys still work but are deprecated, and Positron will prompt you to update your settings.

Before a kernel starts, the kernel status names the interpreter it will start and offers an explicit Start Kernel action. When a cell fails, Fix and Explain buttons send the error to Posit Assistant, matching the Positron notebook experience. The editor also scrolls to reveal output as it is produced, which you can turn off with the new quarto.inlineOutput.autoScroll setting.

Output renders more faithfully as well. The editor gutter now shows which statement is currently executing and per-statement progress. Positron draws images at your display’s pixel ratio, so plots are sharp on retina screens, and Python figures now respect the fig-width and fig-height cell options.

HTML widgets no longer stick in the editor corner when you scroll past them, or trap scrolling instead of letting the document scroll. HTML widgets no longer render as raw HTML after a reload, and collapsed output no longer springs back open when its cell re-runs. Running code in a Quarto document also pins the editor tab now, so Positron does not silently close the document and its session when you open another file.

AI model providers

Positron now reads AI model provider configuration from a single providers.json file rather than a scattered set of settings. The new release will migrate your existing configuration automatically when you start it, and deprecates the authentication.* and positron.assistant.provider.*.enable settings in favor of it. Two new commands give you direct access: Open AI Provider Settings (JSON) opens providers.json from the Command Palette, and Migrate Provider Settings to providers.json runs the migration on demand.

Install missing packages

Positron now notices when your code refers to a package you do not have installed and offers to install it for you. The prompt appears for packages referenced by your scripts and notebooks in both R and Python.

A library() or import call for something missing becomes a single click instead of an error you have to go resolve by hand.

Performance and memory

We continue to invest in the memory footprint, performance, and reliability of Positron. Several components now load only when they are actually needed, and turning off ai.enabled now means Positron never loads some heavy AI-related components at all. We fixed a cluster of long-standing reliability problems around session restarts and lifecycles.

Startup and editing are faster as well. R and Python kernels start much faster on Windows systems with aggressive antivirus software. The interpreter session picker appears immediately instead of waiting for interpreter discovery to finish. We also fixed slow typing, formatting, and saving in long R and Python files.

What’s coming next

• Join our upcoming webinar on August 26 to learn about AI governance in Posit Workbench.
• We are looking forward to posit::conf(2026) next month, where our team will have several sessions on Positron. Register now to join us in person in Houston or virtually from anywhere in the world.

install.packages("roxygen2")

This is a small release, and the two main changes are about performance: one makes your package load faster for your users, and one makes documenting faster for you. You can see the full list of changes in the release notes.

Merged importFrom() directives

@importFrom used to generate one importFrom() directive per symbol. Now it generates a single multi-line directive per package:

# before
importFrom(utils,URLdecode)
importFrom(utils,URLencode)
importFrom(utils,head)
importFrom(utils,tail)

# after
importFrom(utils,
  URLdecode,
  URLencode,
  head,
  tail
)

We made this change because we discovered that the number of importFrom() directives in your NAMESPACE has a surprisingly large effect on loading time. loadNamespace() does a chunk of per-directive work, so the cost grows with the number of directives, not the number of symbols. Importing 1,000 functions with 1,000 separate directives costs around 120ms; importing the same 1,000 functions with one directive per package costs around 9ms, the same as importing 10.

Of course, most packages import far fewer than 1,000 objects. But library() costs are paid by every user, on every session, and they’re cumulative: loading a package also loads its dependencies. Merging the directives removes the cost for the user entirely, at little cost to you as the developer: just one noisy NAMESPACE diff.

My colleague Kevin Ushey also fixed a related annoyance: @importFrom, @importClassesFrom, and @importMethodsFrom once again accept multi-line input, so you can spread a long list of imports over several lines for readability. You’ll just need a hanging indent on the continuation lines.

Faster documenting with rdtools

The other change helps developers, rather than users: documenting a package with lots of cross-references is now considerably faster.

The bottleneck was topic resolution: every time roxygen2 sees a link like [dplyr::filter()], or needs to work out which package an unqualified [filter()] refers to, it has to ask “does this package have a topic with this alias?”. Previously roxygen2 answered that question by calling utils::help(), which takes about 1.5ms. That doesn’t sound like much, but to resolve an unqualified link roxygen2 has to check every dependency plus the base packages, which adds up. On a link-heavy package like testthat, that meant roughly half of the total time spent documenting was just looking up cross-references.

The fix is to stop asking one question at a time, and to cache each lookup. Installed packages already ship an alias index (help/aliases.rds), and packages loaded from source have one maintained by pkgload, so all the information needed is available in bulk — it just needs to be read once and kept in a hash table, rather than rediscovered on every query.

That logic now lives in a new package, rdtools, which provides cached lookup of help topics and aliases across installed, source, and in-development packages, along with efficient retrieval of parsed Rd objects. Pulling it out of roxygen2 deleted a decent amount of fiddly code that I’d also implemented (to varying levels of quality) in pkgdown and downlit.

Acknowledgements

A big thanks to everyone who helped make this release possible! @aphalo, @DavisVaughan, @dragosmg, @etiennebacher, @gadenbuie, @hadley, @jan-swissre, @jemus42, @jranke, @kevinushey, @lionel-, @mcol, @MichaelChirico, @peterdesmet, and @thisisnic.

Data scientists are often forced to choose between the simplicity of the classic Jupyter notebook experience and the advanced capabilities of a general-purpose IDE. With the 2026.07 release, you no longer have to choose: Positron now delivers a first-class Notebook Editor inside an IDE built for data science.

If you’re new to Positron, here’s what the Notebook Editor is like in your daily work.

Environment management

You clone your colleague’s repo and try to rerun their notebook. Which Python version do you use? What dependencies do you install and which versions? Did you previously set up an environment that you could reuse? You’re faced with all of these questions before you’ve run a single line of code.

Positron has several built-in workflows to help you manage your environments. When you open a repo, Positron discovers your installed environments, suggests the right one for the repo, and prompts you to set up a new environment if needed. The active environment is displayed front and center; click to restart or switch environments. Positron uses the same environment across your Jupyter and Quarto notebooks, scripts, and consoles. You can see inside your environments, which packages are installed, their versions, whether newer versions are available, and you can upgrade them. Environments are first-class citizens of Positron. Explore Positron’s environment management.

Interactive data exploration

When you run a cell in your notebook, your variables appear in the Variables Pane. Filter, sort, and search your data in the Data Explorer, and try out plot variations in the Visualize wizard. You can easily convert your point-and-click interactions into code by using the copy-code feature to bring them back into your notebook. If you get stuck, look up library documentation in the Help Pane. All of this works out of the box.

Streamlined version control

Notebooks store outputs and execution metadata alongside code, which is great for sharing but does not work well with version control. Positron includes settings to exclude outputs and execution metadata from the saved file, so the diff is just your code change. Explore the custom settings to clean up your git diffs.

Your notebooks stay ordinary .ipynb files and the editing experience stays classic Jupyter. When a plain-text workflow suits you better, conversion to and from .ipynb and other formats is built in.

AI assistance

Posit Assistant sees your notebook as more than just text. It works with the live session behind the notebook: your variables, your data, your plots. Ask it to fix a chart and it can inspect the dataframe, look at the plot itself, edit the cell, and run it again. It does the same things you would do, using the same panes you use. Explore notebook-aware AI assistance in Positron.

Get started

Download Positron and open a project with a Jupyter notebook. The Notebook Editor is now on by default. If you’re coming from another IDE, your existing .ipynb files will open as-is without any conversion needed.

For the full feature reference, check out our documentation.

If you run into any issues or have ideas on how we can improve Positron, reach out on GitHub.

Already using Positron? Everything in this release is in the release notes.

Thank you so much for helping us build Positron’s Jupyter notebook support from the ground up by chatting with us live, sharing your pain points, and giving us feedback on GitHub!

Today we are announcing the first public release of ir, a small command-line tool that runs R scripts and renders Quarto documents using runtime requirements declared in the file itself.

ir is for one-file workflows that do not quite need a project but still need to be easy to share and rerun later. Simply put the package requirements, and optionally the R version, next to the code. When you render or execute the file, ir resolves the requirements, prepares cached package libraries, and launches R or Quarto with a runtime ready to use.

The interface is inspired by PEP 723 and uv run --script. A script can carry enough metadata to describe its runtime, and the runner can resolve that runtime into a cached environment on demand. ir brings that pattern to R scripts and Quarto documents, using pak, renv, and rig on the R side, and reticulate’s uv-backed helper when Python is part of the runtime.

ir focuses on two workflows:

• running or rendering self-describing scripts and documents
  (ir run, ir render)
• running or installing command-line tools distributed through R packages
  (rx, ir tool install)

Why ir?

R scripts often begin as small, local utilities: a report, a data pull, a model-training or evaluation run, a quick diagnostic, or an example shared with a colleague. Over time, the script can become important, but the setup still lives somewhere else: in a README, in a shell history, in a project library, or in the author’s current R installation.

ir makes the runtime specification part of the source file. That means a script can say, directly:

• which packages it needs
• which R should run it, when that needs to be explicit
• whether user libraries should be visible
• whether CRAN packages should be resolved as of a specific date

This should help you rerun the script reliably at a later date. Keeping the metadata in the file makes it less likely to be lost or fall out of sync with the code.

How ir fits with existing tools

ir sits alongside the R tools people already use and builds on several of them directly:

• rig installs, removes, and switches between R versions on macOS, Windows, and Linux. ir calls rig when a file requests a specific R version, or when date-only exclude-newer needs to select the latest R minor version available on that date. rig is optional for files that only declare packages.
• pak is a fast package installer with a built-in solver. ir uses pak to resolve the dependency graph from a file’s declared packages and fetch them from the appropriate repositories. pak is bootstrapped automatically on first use, so you do not need to install it separately.
• renv gives R projects isolated package libraries and lockfiles. ir uses renv’s global package cache to assemble reusable libraries without creating a renv project or lockfile.

ir builds on that stack for non-project workflows: resolving the runtime for a self-describing script or Quarto document, and running or installing command-line entry points distributed by R packages.

A self-describing R script

Here is a complete script:

#!/usr/bin/env -S ir run
#| packages:
#|   - dplyr>=1.0
#|   - tidyr
#| isolated: true
#| exclude-newer: "2024-01-15"

library(dplyr)
library(tidyr)

mtcars |> count(cyl, gear) |> pivot_wider(names_from = gear, values_from = n)

Run it with:

$ ir run script.R

Or, on macOS and Linux, make it executable and run it directly:

$ chmod +x script.R
$ ./script.R

The metadata block is YAML written in #| comments after an optional shebang. ir reads that metadata, resolves the declared packages with pak, materializes a package library with renv, and starts R with the resolved library at the front of .libPaths().

By default, user libraries remain visible as a fallback. Add isolated: true in the file, or use --isolated at the command line, to run without the user library.

Running R package tools with rx

The ir release also includes rx, a short alias for ir tool run that runs executables provided by R packages.

Package authors can expose command-line entry points through standard package subdirectories such as exec/ and bin/. Files in exec/ can be regular Rscript files, Rapp apps, or direct executable scripts. rx resolves the package, finds the requested executable, and runs it in an isolated library.

For example, this resolves the btw CLI from the btw R package on demand and runs btw --help:

$ rx btw --help

# same as:
$ ir tool run btw --help

For tools you use regularly, install them with ir tool install:

# run once
$ ir tool install btw

# now you only need
$ btw --help

Cached by design

The first run of a new dependency set does the normal work of resolving and installing packages. Later runs reuse cached resolutions and content-addressed package libraries when the same requirements are seen again.

That makes ir useful for both one-off and repeated command-line work. You can run a script, run an inline expression, render a report, or launch a package-provided executable without creating a project directory just to hold the dependency state.

ir also bootstraps its own resolver tooling on first use, so you do not need to pre-install pak or renv.

Reproducibility without a project

For R scripts that need more explicit reproducibility, exclude-newer is usually the first thing to reach for:

exclude-newer: 2024-01-15

You can also provide the same date at the command line:

$ ir run --exclude-newer 2024-01-15 script.R

This resolves packages from the Posit Package Manager snapshot for that date. When no other R selector is set, the same date also tells ir to select the latest R minor version available on that date. If you were writing with the current release of R and current CRAN packages, the date alone is usually enough.

Use r-version when the script really needs a specific installed R version or version range. This selection uses rig:

r-version: "4.3"

Together, these options let a file carry the important parts of its runtime requirements without needing a surrounding project. For reproducibility, most files should need only a list of packages and a date.

Quarto documents too

ir uses the same metadata model for Quarto documents. Put package metadata under an ir: key in the document YAML:

---
title: My report
ir:
  packages:
    - dplyr>=1.0
    - gt@1.0
  isolated: true
  exclude-newer: 2025-05-15
---

Then render with:

$ ir render report.qmd
$ ir render report.qmd --to pdf

When ir selects an R executable using --r-version, frontmatter ir.r-version, or date-only exclude-newer, it sets QUARTO_R so Quarto renders with that R. ir also seeds rmarkdown automatically for knitr-based renders unless you declare it yourself.

Python environments too

Some R scripts and Quarto documents also need Python. In an R script, declare the R packages and Python requirements in the same metadata block:

#!/usr/bin/env -S ir run
#| packages:
#|   - reticulate
#| python-packages:
#|   - pandas
#|   - matplotlib
#| python-version: "3.11"
#| exclude-newer: "2026-06-01"

library(reticulate)
pd <- import("pandas")

ir creates the environment with reticulate’s uv-backed environment helper, sets RETICULATE_PYTHON, and activates the environment for subprocesses. Declare reticulate under packages when the R script loads reticulate.

For Quarto, put Python metadata under the document’s ir: key. A knitr document that uses reticulate can mix R and Python requirements:

---
title: My report
ir:
  packages:
    - reticulate
  python-packages:
    - pandas
  exclude-newer: 2025-01-01
---

For a Quarto document that uses the Jupyter engine, the ir: metadata can contain only Python requirements:

---
title: My notebook
jupyter: python3
ir:
  python-packages:
    - matplotlib
    - pandas
  python-version: "3.11"
---

For Quarto renders, ir injects jupyter into the Python environment, passes the resolved interpreter to Quarto with QUARTO_PYTHON, and also sets RETICULATE_PYTHON so documents that use reticulate see the same interpreter. If the document uses the knitr engine and contains Python chunks, ir automatically adds reticulate to the R package manifest.

When Python metadata is present, exclude-newer is also used for Python environment resolution unless python-exclude-newer is set. Use python-exclude-newer when Python packages should use a different snapshot date from R packages.

Install ir

Install a pre-built binary on Linux or macOS:

$ curl -fsSL https://raw.githubusercontent.com/r-lib/ir/main/scripts/install.sh | sh

Install on Windows PowerShell:

> irm https://raw.githubusercontent.com/r-lib/ir/main/scripts/install.ps1 | iex

The installers download the latest GitHub release and install both ir and rx. You can also download release artifacts from the GitHub releases page or with gh release download.

You will also need R / Rscript; rig is required when selecting R by version or by date-only exclude-newer, and Quarto is required when rendering Quarto sources.

Learn more

The project is open source under the MIT license. To get started:

• Read the documentation: https://r-lib.github.io/ir/
• Browse the source: https://github.com/r-lib/ir
• Open an issue: https://github.com/r-lib/ir/issues

This is a first public release, and feedback is especially useful now. If you try ir on your own scripts or Quarto documents, we would like to hear which workflows feel natural, where the metadata model needs more room, and which command-line edges still need smoothing.

If you work across Python and R or juggle multiple projects with different dependency needs, environment management is probably one of the most challenging parts of your workflow. Positron comes with several out-of-the-box ways to help simplify environment management. Here are a few tips to streamline your workflow.

1: Understand how Positron discovers your environment

Positron does not just look at your system PATH. For Python, it actively discovers venv, uv, pyenv, and conda environments. If Positron is not seeing your project’s virtual environment, you can add custom search locations via the python.interpreters.include setting, or trigger a manual rescan with Interpreter: Discover All Interpreters. Learn more about Python discovery in the Positron documentation.

For R, discovery works differently. Positron consults various sources to build the list of R interpreters. These include your PATH, R root folders based on specific operating systems, well-known executable locations, and on Windows the registry. You can customize your R discovery through a few settings including positron.r.customRootFolders and positron.r.customBinaries. Learn more about R discovery in the Positron documentation.

2. Use the Interpreter Selector

To begin your first session, click “Start Session” in the top right corner and select your preferred R or Python interpreter. Positron can run multiple R and Python interpreter sessions at once, but only one is ever the active session at a given moment. The Interpreter Selector always shows you the active session and its status (idle, busy, or shut down) and you can use it to switch between or start additional sessions.

3. Install Python with uv

If Positron does not find a usable Python on your machine, it will offer to install Python via uv to help streamline your setup. If you prefer to manage the installation yourself, you can disable uv with the python.allowUvPythonInstall setting. Check out our blog post exploring on-demand Python installation in Positron or explore configurations in our Python installation documentation.

4. Manage packages with the Packages Pane

The Packages Pane in Positron lets you manage the packages installed in your active session. Whether you use pip, uv, conda, pak, base R, or renv, you can browse installed packages and search package repositories. You can also track outdated packages and install, update, or uninstall packages without leaving Positron or writing any code.

5. View package documentation

If you need to learn more about a specific package, the Packages Pane has buttons to navigate to the source documentation or link to the package’s website. You can also pull up the Help Pane for any reference in the Console using the ? operator, including both packages and functions.

6. Start projects with New Folder from Template

The New Folder from Template flow helps you start new projects faster. Instead of running multiple setup commands you can make a few selections and Positron helps you set up an environment directory, version control, directory structure, and an interpreter instance. Learn more about the Python and R templates available in the documentation.

7. Make use of the Command Palette

We recommend taking advantage of the following commands when managing your environments:

• Interpreter: Discover All Interpreters: Find new interpreters
• Interpreter: Select Session: Select a running interpreter session
• Python: Create Environment: Create a new virtual environment

8. Let Posit Assistant help manage your environment

Posit Assistant has knowledge of your R and Python session including the language, version, names, and types of variables in your environment. You can prompt Posit Assistant to set up environments and troubleshoot issues you run into.

Have an idea for how we can improve environment management in Positron? We would love to hear from you in a discussion on GitHub.

Welcome back to another edition of our monthly Positron updates! Each month we share highlights from our latest release and useful resources. Last release we told you that several major features were on track to leave preview in July, and the time is now here! The new Notebook editor, the Packages pane, and Posit Assistant are all now generally available.

Positron Notebook Editor

Positron’s new Notebook editor is now the default experience for Jupyter (.ipynb) files. This release brings a long list of additions, including split-pane editing, cell tag management, and executing a line or selection within a cell with Cmd/Ctrl+Shift+Enter. You can export notebooks to Quarto, Python, or R, and inline PDF rendering makes it easier to work with generated output. If you are coming from JupyterLab, you will find familiar keyboard shortcuts, and we have improved output fidelity for Mermaid diagrams, htmlwidgets, and ipywidgets.

Posit has built on and for the Jupyter ecosystem for years now, and we are excited to have recently joined the Jupyter Foundation.

Packages pane

The Packages pane has also come out of preview. It gives you a live view of the R and Python packages installed in your active session, so you can search, install, update, and remove packages, and jump to their documentation, without leaving Positron.

This release also makes the pane more capable. Clicking a package opens a detail editor with its overview, metadata, and actions, similar to the Extensions pane. Installing a package searches results as you type, and each row has a button that opens the package’s website. Update indicators appear immediately on a new session from a cached snapshot, and Update All Packages reports exactly what changed. Package operations keep your environment consistent too, resolving against a workspace requirements.txt for Python and updating the renv.lock snapshot for R.

Posit Assistant

Posit Assistant, our unified, data-science-focused approach to AI assistance, is now out of preview and generally available; Posit Assistant fully replaces the legacy Positron Assistant. We know the names are similar, and Joe Cheng recently walked through a bit of the story behind how our AI agent tools have evolved.

This release also gives you finer control over AI in Positron. The new ai.enabled setting turns off every Positron AI feature at once, and administrators can enforce it; notebook.ai.enabled does the same for notebooks specifically. The set of language model providers keeps growing, with DeepSeek joining as an experimental provider and Microsoft Foundry reaching general availability. The configuration modal now shows every provider by default with preview and experimental badges.

Data Explorer

The Data Explorer can now open Excel workbooks directly, with no code required, without first needing to load it via Python or R. Sort, filter, and profile columns, switch between worksheets, and toggle whether the first row holds column names. An Open in Excel button opens the workbook in your native spreadsheet application.

This release broadens what you can open in the Data Explorer overall. Backed by a native DuckDB engine, it now also previews compressed CSV, TSV, and Parquet files. Also, a new Open in Data Explorer code action, from the editor lightbulb or Cmd+., opens the data frame under your cursor in R, Python, and Quarto files, so you can jump straight from your code to exploring your data.

R language intelligence

Last release we introduced within-file symbol resolution for R; this release expands it across files. Go to Definition, Find References, and Rename Symbol now work across the packages and scripts in your workspace, and diagnostics and workspace symbols react to external file changes so your language intelligence stays in sync as your project evolves.

What’s coming next

• New in preview this release, Data Connections lets you browse the schemas, tables, views, and indexes of a database, open tables in the Data Explorer, and generate connection code. It currently supports DuckDB, PostgreSQL, and SQLite. Learn how to try it out and tell us what you think in the Data Connections discussion post: which databases and warehouses you need, whether the connection setup is clear, and anything confusing, missing, or broken.
• We are looking forward to posit::conf(2026) in September, where our team will have several sessions on Positron. Register now to join us in person in Houston or virtually from anywhere in the world.

If you’re new to Python, Positron has a few built-in workflows to help you skip that installation pain entirely. Most of it is powered by uv, created by Astral. We chose uv because it’s fast and has quickly become widely adopted across the Python community. Behind the scenes, uv handles the heavy lifting, downloading Python versions and building environments. Positron wraps that power in a friendly interface, so you never have to remember a command.

From zero to Python in one click

If you don’t have a suitable Python available, Positron will offer to install it for you. When you go to start a Python runtime through the Start Session button, you’ll see an option for + Install Python via uv.

When you choose it, Positron will ask to install uv for you if you don’t already have it. Then it shows you the supported Python versions (currently 3.9 through 3.14) and installs whichever one you pick. If you have a folder open, it will also offer to create a virtual environment for the project and start a Python console session using that environment. Once you have a Python available, this option disappears from the session picker.

If you’d rather not see the prompt to install Python, you can turn it off with the python.allowUvPythonInstall setting (enabled by default).

On-demand Python installation

You don’t have to wait for Positron to ask, either. Open the command palette with Cmd/Ctrl+Shift+P and run Python: Install Python via uv any time you’d like another version. This command will download uv if needed, show you the available Python versions, and optionally offer to create a virtual environment.

Since it runs on demand, it’s a good way to add another interpreter to a project you’ve already set up. And because it follows the same flow every time, it works well for teaching, since everyone ends up in the same place, the same way.

Automatic project setup support

Setting up a virtual environment isn’t limited to that first run. If Positron finds a pyproject.toml or requirements.txt in a project that doesn’t have a virtual environment yet, it’ll offer to create one with uv and install your dependencies. This comes in handy when you’ve cloned a colleague’s project and want to get up and running without extra setup.

If there’s a single requirements source, like a lone requirements.txt or pyproject.toml, Positron will prompt you to create a .venv and install everything right away. And if there are several sources, you can choose which files to include in your installation.

Positron also knows when to stay out of your way. If you already have a local virtual environment, or if you use non-uv files like environment.yml, Pipfile, or poetry.lock, you won’t get a prompt at all.

Try it yourself

Setting up Python doesn’t have to feel like a chore, whether you’re starting on a brand new machine, picking up a colleague’s project, or getting a room full of students ready to code.

Give it a try in Positron’s July 2026 release and let us know what you think.

If you use Positron, the Air Extension has probably already updated you to the new release! Otherwise, follow one of Air’s editor guides to install the latest version for your editor.

To see every bug fix, check out our CLI changelog and extension changelog.

Assignment style 😎

The headlining feature of 0.10.0 is a new assignment-style option, one of our top requests! This allows you to enforce <- or = for assignment throughout your codebase. Choose one of "arrow" for <-, "equal" for =, or "preserve" to leave existing code as is. For example, with assignment-style = "arrow":

# This
a = 1
fn = function(x, y) {
  z <- x + y
  z
}

# Is standardized to
a <- 1
fn <- function(x, y) {
  z <- x + y
  z
}

This option defaults to enforcing <- everywhere, which is what the style guide already recommended. Note that this is a breaking change for Air, as the previous behavior didn’t enforce any assignment style. To revert to the old behavior, use "preserve".

This feature is surprisingly sophisticated! In R, you can always convert from = to <- without changing the meaning of the code, but the reverse isn’t true. Consider the following:

quote(x <- 1)

This quotes the expression x <- 1 and returns it. Blindly changing to = results in:

quote(x = 1)

That’s very different! This sets an argument named x to 1. Trying to run this will result in an error since quote() doesn’t have an x argument. Air knows every case where <- is allowed but = isn’t, so you can rest assured that this option won’t impact the meaning of your code in any way.

Positron terminal support

Positron’s integration with Air has gotten even better! When the Air extension activates, it now prepends the bundled Air executable to your integrated terminal’s PATH. This means:

• You can now run Air commands from Positron’s terminal, even without installing the CLI separately.
• Your terminal version of Air should now always match the version used by the editor itself.

This is particularly useful with agents like Claude Code, where you’ll often want to tell your agent to run Air on any R files it touches (see usethis::use_tidy_agents() in the development version of usethis for a way to automatically add this to an AGENTS.md).

If you’ve already installed the Air CLI separately, note that the bundled version will take precedence in Positron’s terminals by default. To force both the editor and the integrated terminal to use your externally installed version of Air, set air.executableStrategy: "environment". To opt-out of terminal support, set air.addExecutableToTerminalPath: false.

RStudio improvements

Thanks to Kevin Ushey, RStudio’s support for Air is improving rapidly!

Note that you’ll need RStudio 2026.06.0 for this, which isn’t out yet, but should be by the end of next week.

RStudio now has “native” support for Air, rather than just being configurable as an External Formatter. If you opt-in to Air, RStudio will now automatically download the latest version of the air binary the first time you save a file, making the whole experience much smoother.

You can turn this on via Tools -> Global Options... -> Code -> Formatting. I recommend checking both Use Air for code formatting and Reformat documents on save.

Lions, tigers, and bears uv, pixi, and mise, oh my!

Air now lives on PyPi as air-formatter (sadly air was already taken), which means that you can now install Air’s CLI via uv:

# Install globally
uv tool install air-formatter
air format path/to/file.R

# Run one-off command
uvx --from air-formatter air format path/to/file.R

It might sound a little absurd to put an R code formatting tool on Python’s PyPI, but in a world where an increasingly large number of R users are also uv users, it’s pretty darn convenient to be able to invoke it this way!

Additionally, Air is on conda-forge thanks to @salim-b, which means you can also install it with pixi and mise:

# Add to a project
pixi add air
mise use conda:air

# Install globally
pixi global install air
mise use --global conda:air

# Run one-off command
pixi exec air format path/to/my/script.R
mise exec conda:air -- air format path/to/my/script.R

pre-commit support

Air now has pre-commit and prek support via posit-dev/air-pre-commit. To run Air on changed R files before every commit, add the following to your .pre-commit-config.yaml:

repos:
- repo: https://github.com/posit-dev/air-pre-commit
  # Air version
  rev: 0.10.0
  hooks:
    # Run the formatter
    - id: air-format

stdin support

Air’s CLI now has stdin support! You can activate this with the new --stdin-file-path option like so:

cat R/across.R | air format --stdin-file-path R/across.R

air will receive the contents of cat R/across.R on stdin, format it, and then emit the formatted result back out on stdout.

You typically won’t call this directly, but it’s very useful for editors and IDEs without full language server support. For example, with Zed you can configure Air as an external formatter with the following setup:

"formatter": {
  "external": {
    "command": "air",
    "arguments": ["format", "--stdin-file-path", "{buffer_path}"]
  }
}

This allows Zed to invoke Air on every file save.

Note that Zed does have full language server support, and it’s recommended to use our Air extension for Zed instead, but it makes for a nice example anyways!

Invoking Air via stdin can also be useful in some embedded contexts, such as inside arf, an R console.

Shell completions

Thanks to @salim-b, Air can now generate shell completions for itself via a new air generate-shell-completion <shell> command, where <shell> can be one of zsh, bash, powershell, fish, or elvish. Read the documentation for how to set this up for your specific shell. With shell completions set up, you can Tab your way through air commands at the command line:

debrief is on CRAN:

install.packages("debrief")
# or the development version:
pak::pak("r-lib/debrief")

From guessing to measuring

Prompt an AI agent to make your R code faster, and it will either declare that a bottleneck exists without evidence, or try to use Rprof() directly. We find that profvis() is better and easier to use than Rprof() directly, as it provides a more user-friendly interface and visualizations. But that interface is designed for human eyes, not for an LLM reading a transcript.

This is where debrief comes in. It turns the output of profvis() into a text-based summary that can be easily read and understood by AI agents. Every function is prefixed pv_ (for profvis) and returns text designed to be read top to bottom:

library(debrief)

p <- profvis::profvis(slow_function(data))
pv_print_debrief(p)
#> ## PROFILING SUMMARY
#>
#>
#> Total time: 190 ms (19 samples @ 10 ms interval)
#> Source references: available
#>
#>
#> ### TOP FUNCTIONS BY SELF-TIME
#>    110 ms ( 57.9%)  paste
#>     20 ms ( 10.5%)  <GC>
#>     10 ms (  5.3%)  .bincode
#>     10 ms (  5.3%)  any
#>     10 ms (  5.3%)  anyDuplicated.default
#>     10 ms (  5.3%)  apply
#>     10 ms (  5.3%)  rnorm
#>     10 ms (  5.3%)  unlist
#>
#> ### TOP FUNCTIONS BY TOTAL TIME
#>    180 ms ( 94.7%)  FUN
#>    180 ms ( 94.7%)  lapply
#>    180 ms ( 94.7%)  process_data
#>    140 ms ( 73.7%)  summarize_data
#>    110 ms ( 57.9%)  paste
#>     30 ms ( 15.8%)  clean_data
#>     20 ms ( 10.5%)  <GC>
#>     20 ms ( 10.5%)  apply
#>     10 ms (  5.3%)  .bincode
#>     10 ms (  5.3%)  [.data.frame
#>
#> ### HOT LINES (by self-time)
#>    120 ms ( 63.2%)  analysis.R:22
#>                    list(
#>     10 ms (  5.3%)  analysis.R:9
#>                    x <- rnorm(n)
#>
#> ### HOT CALL PATHS
#>
#> 110 ms (57.9%) - 11 samples:
#>     lapply
#>   -> FUN
#>   -> process_data
#>   -> summarize_data (analysis.R:5)
#>   -> paste (analysis.R:22)
#>
#> 10 ms (5.3%) - 1 samples:
#>     base::tryCatch
#>   -> any
#>
#> 10 ms (5.3%) - 1 samples:
#>     lapply
#>   -> FUN
#>   -> process_data
#>   -> clean_data (analysis.R:4)
#>   -> [.data.frame (analysis.R:15)
#>   -> anyDuplicated.default
#>
#> 10 ms (5.3%) - 1 samples:
#>     lapply
#>   -> FUN
#>   -> process_data
#>   -> clean_data (analysis.R:4)
#>   -> cut.default
#>   -> .bincode
#>
#> 10 ms (5.3%) - 1 samples:
#>     lapply
#>   -> FUN
#>   -> process_data
#>   -> clean_data (analysis.R:4)
#>   -> scale.default
#>   -> apply
#>   -> FUN
#>   -> <GC>
#>
#> ### MEMORY ALLOCATION (by function)
#>    51.28 MB paste
#>    10.01 MB anyDuplicated.default
#>     2.90 MB any
#>     1.62 MB rnorm
#>
#> ### MEMORY ALLOCATION (by line)
#>    51.28 MB analysis.R:22
#>             list(
#>     1.62 MB analysis.R:9
#>             x <- rnorm(n)
#>
#> ### Next steps
#> pv_focus(p, "paste")
#> pv_source_context(p, "analysis.R")
#> pv_suggestions(p)
#> pv_help()

pv_print_debrief() is meant as the first entry point after profiling. It gives a comprehensive overview of the profile with a number of sections.

• Top functions by self-time and total time
• Hot lines and hot call paths
• Memory allocation by function and by line
• Next steps

Both the hot lines and hot paths sections link back to source references when available, Especially relevant if the bottleneck is happening in a common function name like paste() that is scattered across your package. With this, we know exactly which paste() call is the culprit.

Each function in {debrief} also prints the name of the possible next functions to run, so the assistant can drill down into the details.

debrief is a new package. Its output almost certainly isn’t part of any model’s training data. And output is also very unlikely to be added, as profiling code is rarely committed. This means that the package tries to be self-documenting by design, With the hope that an AI agent doesn’t need to read the documentation to understand how to use it.

Getting an agent into the session

While you can use debrief with any AI agent, it works better with agents that keep a persistent R session. Otherwise, it will need to rerun the profile every time it wants to check the results of an edit. You also won’t be able to take full advantage of the “Next steps” hints, which are designed to guide the agent through drilling down into the profile.

Posit Assistant is the easiest way to do this. It runs in the same session as you, so you can be a bigger part of the process. The same assistant runs in Positron, RStudio, or the terminal, so you can profile interactively or drive the whole loop headlessly from the pa CLI.

If you aren’t using RStudio or Positron, or prefer an agent like Claude Code or Codex, mcp-repl gives you the same thing. It’s an MCP server that hands any MCP-capable agent a persistent R (or Python) session, so you can load debrief and run the profiler once, then drill down as needed.

Trying it out

The point of debrief is to put profiling results in a form an agent can easily interact with, so it can measure instead of guess and iterate toward faster code. We have already used it this way: tidymodels/textrecipes#309 is a profiling-driven optimization of step_word_embeddings(), where each round of profile, read, change, and re-measure was guided by debrief’s summaries.

Install debrief, point an agent at a slow function, and let it profile.

One of the least fun aspects, though, is that you never have time to do most (or even half) of the great ideas that bubble up through the community. RStudio’s issue tracker is full of worthy requests that have been unimplemented for years, often because they would require outsized changes to the core system’s architecture or behavior.

When we set out to make Positron, RStudio’s issue tracker became a gold mine of possibilities. Because Positron has a new architecture and is built on a different platform, many of the things that we’d never been able to do in RStudio suddenly became possible.

Today, we take a look at 10 of the most upvoted RStudio feature requests of all time and how those features have been incorporated into Positron. Every one of these 10 requests is on the front page of the most-upvoted RStudio issues as of this writing.

#1: Fully configurable pane layouts

Most IDEs have a somewhat more flexible system which allows for arbitrary tab arrangement, often using mouse gestures to edit configuration on the fly.

– #2879

This has been one of RStudio’s most-upvoted requests for years. In Positron, this feature is largely inherited from upstream Code OSS (the open source core of VS Code). It has a very flexible layout system which allows tabs to be rearranged, split, hidden, and more with natural dragging and mouse gestures, or via context menus. Try right-clicking on any tab or divider to show places you can move it:

Read more about it here:

VS Code Layout Configuration

Positron also ships with a variety of layout presets customized for specific tasks. Try the View: Stacked Layout command to make it look more like RStudio, or View: Notebook Layout to focus on a Quarto document or Jupyter Notebook.

#2: Fixed size graphics device

It would be excellent if one could set the RStudio graphics device to generate plots as they would be generated by a non-interactive device with fixed dimensions, so that one could do iterative plot-making within the IDE rather than call png(), look at the outputs in another program, and then fiddle with font scaling, etc. and repeat.

– #4422

RStudio always draws plots to fit the exact dimensions of its Plots pane, which can make it difficult to iterate on a plot you’re preparing for publication.

When we added a Plots pane to Positron, we included a new tool that lets you indicate the dimensions at which you’d like the plot to draw. You can have it fit to some common aspect ratios or – as in the RStudio feature request – specify the exact size at which you’d like the plot to be drawn.

Positron’s Plots pane also features a visual history browser, and it remembers the code used to create the plot so you can jump to it or re-run it.

#3: Multi-line statement support for Python code

It would be really great to have RStudio support of multi-line statements extended to Python code as well.

– #9014

One of RStudio’s key R features is multi-line statement detection. When you tell RStudio to execute R code at your cursor location, it doesn’t just send the current line of code; it gathers all the lines that are part of the statement and sends them together. RStudio doesn’t know how to do this for Python, however.

In Positron, Python and R are peers, and we’ve implemented multi-line statement detection for Python, too. Placing your cursor anywhere in a Python statement and invoking Run will execute the whole statement.

#4: Tree view for browsing files and directories

Hi, is there any plan for browsing files and directories in tree view mode?

– #2552

RStudio’s file browser lists only one directory at a time. Positron inherits Code OSS’s tree-based explorer, which not only shows files and directories in context but even has customizeable icons!

#5: View different parts of a source file at the same time

In TexShop there’s an option to split source which allows you to see (and edit) multiple areas in a document in one window so that you don’t need to keep scrolling up and down. It would be wonderful to have this as a functionality in the RStudio IDE editor

– #2129

In Positron, you can have several editors open at once against the same file. With a file open, try using the Split Right or Split Down commands, which will create a second tab for the file that can be scrolled independently. You can access this via the Command Palette, or via the editor action toolbar:

#6: Add builds for Windows on ARM

RStudio is built for Windows only for Intel (x86) processors. However, there is now a version of Windows 11 available for ARM based processors.

– #11977

Microsoft has taken a page from Apple’s playbook and started producing its own ARM-based hardware, such as the ARM-based Surface devices, and ARM-based Windows PCs are also now available from third-party manufacturers.

When we built Positron, we designed its native components to be easy to recompile against different CPU architectures. On Windows, Positron includes both x64 and arm64 R computation engines (kernels), so it can run natively with both x64 and arm64 versions of R. Its Python support, likewise, works great on ARM-based PCs.

#7: Persistent Julia engine

It would be useful if we can use Julia in RStudio seamlessly as well as Python.

– #1798

One of the main architectural goals of Positron was to make it adaptable to any language. It is a data science platform that supports “language extensions”. Positron’s Python and R support subsystems are included in your Positron download, but are implemented as extensions.

While Posit doesn’t currently have the expertise to develop well-rounded support for Julia, that hasn’t stopped the community from creating a Positron extension that you can install to add Julia support. When installed, Julia becomes a peer of R and Python in Positron, and connects to Positron’s Console, Variables, History, Packages, and Plots panes.

Find it here: Julia for Positron

One of the questions we get a lot is why Positron itself isn’t a VS Code extension. This is one of the reasons why: Positron isn’t an extension; it has extensions.

#8: Teaching/presentation mode

Quite a lot of people use RStudio hooked up to a projector to teach others. It would be great if those people had a key combo that could toggle between their current theme settings and some good defaults suitable for teaching/demos. … Perhaps the ultimate goal would be to have the teaching mode itself configurable.

– #4276

In Positron, it is possible to define different “profiles” that have different themes, font sizes, and other settings, and switch between them from the Command Palette, so it is possible set up a “Presentation” profile with a high-contrast theme and large text.

Profiles go beyond just layouts and themes. More documentation here:

https://code.visualstudio.com/docs/configure/profiles

#9: Fix columns or rows when scrolling data

The data viewer is one of the most used tool of data analysis in RStudio. However, a very useful feature is missing. In horizontal scrolling a big table with lots of column (it’s very common to have more columns than one screen can fit), it will be very helpful to fix the row name column so that it’s always visible(i.e. always keep it within screen with scrolling). … More generally, sometimes we also want to fix certain columns so that it remains visible when scrolled horizontally. The row name column is just a special case of this request.

– #3463

It’s pretty common to have a column of data that represents a key value or name for the observation, or a value to which you wish to compare other values. In Positron, you can pin any column to fix it to the left, so that it is always visible as you scroll the other columns horizontally. Click on the column’s action menu (vertical ellipsis) and choose Pin Column.

You can also pin rows! Right-click on the row and choose Pin Row.

#10: Remove all objects in the Python environment

Normally, we can do it easily in R environment by just 1 click but Python doesn’t support it.

– #8750

It’s supported in Positron! With a Python session open in the Console, you can use the trash icon to clear all the objects from the session – in one click.

… And a lot more.

Some of our other favorite Positron-only features that don’t have a top-upvoted RStudio issue attached:

• Multiple R sessions: RStudio runs only one primary R session at a time; any concurrent work needs to be done in a non-interactive background job. Positron supports multiple concurrent interactive R sessions.
• Multiple R versions: RStudio can only work with one R version at a time, and you need to switch externally using a tool like rig. Positron will let you choose from any R installation on your system and can even associate specific R versions with specific projects.
• Crash recovery: RStudio crashes when R does, but in Positron all you’ll lose is the R session itself, which just gets safely restarted.
• Remote sessions: Connect remotely to another computer over SSH and run R sessions inside it, or work with reproducible projects inside devcontainers.

See Comparing RStudio and Positron Features for more.

What about RStudio?

While Positron’s design has made it more practical to make many of these advancements, the point of this post isn’t that you should switch to Positron if you’re happy in RStudio. In fact, features are also flowing in the other direction; many of Positron’s features are making their way back into RStudio. For example, the latest release of RStudio has:

• a redesigned data viewer inspired by Positron’s data viewer;
• code formatting optionally powered by air, Positron’s R formatter;
• warning/error styling in the R console inspired by Positron’s Console; and, of course
• Posit Assistant, a platform-agnostic data analysis assistant that works in both IDEs.

If you use RStudio and are interested in trying Positron, a good place to start is our Migrating from RStudio guide.

Thank you for the creativity, ideas, and support you’ve shown our IDEs over the years. Keep it coming!

Welcome back to another edition of our monthly Positron updates! Each month we share highlights from our latest release and useful resources.

Posit Assistant

Last release we introduced Posit Assistant, our unified, data-science-focused approach to AI assistance. This release continues that work, and we want to give you advance notice that the older Positron Assistant will be deprecated in the next release. If you are still using Positron Assistant, we encourage you to migrate to Posit Assistant now.

Posit Assistant supports the same broad set of providers as Positron Assistant, along with the Posit AI model provider and new experimental support for Google Vertex. Learn more about the differences between the new Posit Assistant and the older Positron Assistant:

You may also be interested in comparing Posit Assistant and Claude Code.

New in Posit Assistant this release, you can use the Posit AI model provider for Next Edit Suggestions, which propose your likely next change as you edit. You can also access the Configure Language Model Providers item in the accounts menu. You can ask a question, report a bug, or request a new feature for Posit Assistant separately from Positron now, but don’t worry too much about where to send your feedback; we will help route it to the right place!

Packages pane improvements

We introduced the Packages pane last release, and this release makes it more informative and flexible. A Show Help button and context menu entry on every package take you straight to its documentation in the Help pane. You can now combine category filters as an intersection, so you can narrow the list to, for example, packages that are both attached and outdated. A new Item Size toggle lets you switch between a compact row view and a richer card view that surfaces package descriptions and other metadata.

For R users, the new packages.r.installer setting controls whether installs, updates, and removals use pak, base R, or an automatic choice. The setting that controls the pane has been renamed to packages.enabled; the previous positron.packages.enable setting is deprecated but still honored.

Inline output for Quarto

Inline output for .qmd documents was one of Positron’s most-requested features ever, and it is now out of preview. A new toolbar button in Quarto documents gives you one-click access to running cells, managing inline output, and showing the console.

Inserting code into a Quarto document from the History pane now automatically wraps it in cell markup when you drop it into a prose region. You can opt into inline output with the positron.quarto.inlineOutput.enabled setting.

Faster startup

We continue to invest in performance improvements, and Positron starts up even faster in this release. Positron now caches previously discovered system interpreters, dramatically speeding up startup in new folders and projects; you can control this with the new interpreters.discoveryCache.enabled setting. On Windows, we fixed multi-minute startup delays by skipping slow PATH discovery by default, governed by the new positron.r.interpreters.pathDiscoveryMode setting. We also fixed an occasional hang at “Preparing” when starting Positron after updating to a new version.

A more customizable interface

This release gives you finer control over Positron’s chrome so you can tailor the interface to your workflow. Several layout settings that previously weren’t always honored now work as expected:

• workbench.topActionBar.visible reliably hides and shows the top action bar at runtime
• workbench.secondarySideBar.defaultVisibility is respected when you set it explicitly
• workbench.secondarySideBar.showLabel lets Secondary Side Bar items render as compact icons

You can also enable window.commandCenter to bring the command center into the title bar. Learn more about some of our own team members’ favorite customizations:

R language intelligence

Positron’s R language support now understands symbols within a file. You can rename a local symbol and have every use of it updated at once, and Go to Definition and Find References now work for local symbols, so you can jump to where a variable is defined (such as via <- or a function parameter) or see everywhere it is used within a function. Renaming symbols across files is not yet supported, but it is coming soon.

What’s coming next

• We have some exciting milestones planned for our July release! The new notebook editor for .ipynb files, the Packages pane, and Posit Assistant will all come out of preview to general availability. We are thrilled for these features to be ready for your production workflows, and we hope you will give them a try and share your feedback.
• We’re still prototyping first-class SQL editing and execution in Positron, including support for visualizations with ggsql. We’ll share more as this takes shape, and in the meantime, let us know your thoughts and current pain points!
• If you will be at the Databricks Data + AI Summit next week, join us to learn about using Positron and Workbench within the Databricks platform.
• We are looking forward to posit::conf(2026) in September, where our team will have several sessions on Positron. The conference program was released last week and we are pretty excited about everything happening! Register now to join us in person in Houston or virtually from anywhere in the world.

The case against YAML was, for a long time, a reasonable one. The format attracted its critics for real reasons, through years of surprising behavior that burned even careful users. But the specification evolved, and the tooling is finally catching up. To understand why the current consensus is outdated, we need to trace the lineage of configuration formats themselves, because this sort of argument has played out before.

A brief history of configuration formats

The INI file emerged in the early 1980s alongside MS-DOS and the first versions of Windows.¹ It was the simplest thing that could possibly work: key-value pairs, grouped into sections denoted by square brackets, with semicolons for comments. They are flat, readable, and human-editable. For the needs of that era (like configuring device drivers, specifying font paths, or setting application preferences) it was entirely adequate. Its only real limitation was structural: you could not nest deeper than one level, and there was no formal specification, which meant every parser implemented its own dialect. But for two decades, this was fine.

[boot]
shell=COMMAND.COM
device=HIMEM.SYS

[display]
resolution=640x480
colors=256

Then came XML. In the late 1990s, the enterprise software world adopted angle brackets broadly. XML could represent arbitrary hierarchy. It had schemas, namespaces, transformations. It was self-describing. For a while it seemed as though the debate was settled. But XML configuration files grew large in practice. Anyone who maintained a Java web.xml or an Ant build file in 2003 knows what it was like to edit dozens of nested elements just to change a database connection string. The verbosity made the files difficult to maintain by hand, which is precisely what configuration files demand.

<web-app>
  <servlet>
    <servlet-name>myServlet</servlet-name>
    <servlet-class>com.example.MyServlet</servlet-class>
    <init-param>
      <param-name>database.url</param-name>
      <param-value>jdbc:postgresql://localhost/mydb</param-value>
    </init-param>
  </servlet>
</web-app>

JSON appeared as the lightweight reaction. Douglas Crockford, who claims to have discovered rather than invented the format,² offered the simplicity of the JavaScript object literal: curly braces, square brackets, quoted strings, and a tiny set of types. JSON displaced XML in web APIs through the late 2000s and early 2010s. But as people began using it for configuration (rather than machine-to-machine data exchange), its limitations became apparent. JSON has no comments. It has no multiline strings. Trailing commas are illegal. These are reasonable constraints for a serialization format, but they make JSON miserable for files that humans must author and maintain. The removal of comments from JSON’s spec was, according to Crockford himself, motivated by people abusing them for parsing directives.³ It was the right call for data interchange, but it left a gap.

YAML (2001) and TOML (2013) each arose to fill that gap, and both positioned themselves explicitly against what came before. YAML offered the full expressive power of a serialization language (including arbitrary nesting, multiple documents, references, and custom types) with a syntax built on indentation rather than brackets. TOML, created by Tom Preston-Werner a dozen years later, was a reaction to YAML’s complexity: it aimed to be a “standardized INI” with explicit typing, obvious semantics, and a formal specification.⁴ The pattern repeats in each generation: the previous format’s excess becomes the new format’s founding grievance. What is interesting about the current moment is that YAML’s problems were not inherent to the format’s design. They were artifacts of a particular specification version and the parsers frozen on it.

The case against YAML (as it was)

The criticisms of YAML are not fabricated. They reflect real experiences that real programmers had over many years.

The most infamous problem is the Norway incident, which has become shorthand for YAML’s implicit typing behavior. In YAML 1.1, the bare scalar NO was interpreted as the boolean value false. This meant that a list of country codes would silently transform Norway into a falsehood:

# What you wrote:
countries:
  - dk
  - fi
  - is
  - no
  - se

# What YAML 1.1 parsed:
["dk", "fi", "is", false, "se"]

The same applied to yes, on, off, y, n, and various capitalizations thereof. Ruud van Asseldonk’s widely-circulated “YAML Document from Hell”⁵ catalogued these and other problems: port mappings like 22:22 parsed as sexagesimal (base-60) integers, version numbers like 10.23 parsed as floats rather than strings, date-like values parsed as timestamps,⁶ and tags beginning with ! could trigger arbitrary code execution in some parsers.

This is not only a country-code problem. In data science and machine learning code, n and y are natural variable names:

variables:
  x: features
  n: sample_size
  y: target

Under YAML 1.1’s implicit boolean rules, a parser can resolve those keys as booleans instead of strings:

{"variables": {"x": "features", False: "sample_size", True: "target"}}

These were not edge cases encountered only by the reckless. They emerged from the YAML 1.1 specification’s design philosophy of aggressive implicit typing, where the parser attempted to be “helpful” by guessing the intended type of unquoted values. The intention was readability (you could write true without quotes and get a boolean), but the result was unpredictable behavior in practice. Configuration files are precisely the domain where surprising behavior is least tolerable. They are edited infrequently, often by people who did not write the original file, and a silent misparse can propagate through a system undetected for months.

The complexity of the full specification compounded the problem. The YAML 1.2.2 spec runs to ten chapters with sections numbered four levels deep.⁷ There are dozens of ways to express multiline strings. Anchors and aliases create a reference system that, while powerful, adds conceptual weight far beyond what most configuration tasks require. And the security implications of tag-based object deserialization (the yaml.load() vulnerability in Python) became a well-known attack vector.⁸ All of these criticisms were valid, and they were valid specifically of YAML 1.1 and the tooling ecosystem built around it.

What TOML gets right

TOML deserves some credit. For flat or shallow configuration structures, it is clean, readable, and unambiguous. The syntax is familiar to anyone who has seen an INI file, but with the addition of explicit types, a formal specification, and support for nested tables via dot-separated keys.

Consider a pyproject.toml or a Cargo.toml. These files are typically one or two levels deep, with well-defined sections and predictable content. TOML handles them well. Strings are always quoted, so there is no ambiguity about whether no is a boolean or the word “no”. Integers are integers, floats are floats, and dates are first-class types. Comments work exactly as you would expect. For this class of problem, TOML works well, and its adoption by the Python packaging ecosystem (PEP 518)⁹ and the Rust community (Cargo) makes sense.

TOML also benefits from simplicity of implementation. The specification is short enough that a competent programmer can write a compliant parser in a weekend. This means that the ecosystem of parsers is large, well-tested, and consistent. There is no equivalent of the YAML 1.1/1.2 version split. TOML 1.0 is TOML 1.0, everywhere. These are real advantages.

Where TOML strains

The trouble begins when configuration needs to express depth. TOML’s handling of nested structures relies on either dot-separated section headers ([servers.alpha]) or arrays of tables ([[products]]), both of which become difficult to read as the nesting increases. This is not a theoretical concern: it is the reason that Martin Vejnár, the author of the PyTOML parser, eventually abandoned his own project. When asked whether his library should become a dependency for pip, he declined and explained: “TOML is a bad file format. It looks good at first glance, and for really really trivial things it is probably good. But once I started using it and the configuration schema became more complex, I found the syntax ugly and hard to read”.¹⁰

Consider a moderately complex configuration. In YAML, the indentation communicates the hierarchy at a glance:

services:
  web:
    image: nginx:latest
    environment:
      DB_HOST: postgres
      DB_PORT: 5432
    resources:
      limits:
        memory: 512M
        cpu: "0.5"

The equivalent in TOML requires repeating the full path in each section header:

[services.web]
image = "nginx:latest"

[services.web.environment]
DB_HOST = "postgres"
DB_PORT = 5432

[services.web.resources.limits]
memory = "512M"
cpu = "0.5"

The reader must mentally reconstruct the tree from a flat sequence of qualified names. The StrictYAML documentation measured this concretely: equivalent TOML files use approximately 50% more characters to represent the same data, largely because of the repeated path prefixes.¹¹

There is also the matter of meaningful indentation itself. Python demonstrated decades ago that indentation as structure is not a weakness but a strength: it eliminates the class of bugs where visual structure disagrees with syntactic structure. YAML inherits this property. TOML does not require indentation (though many authors add it voluntarily, as a non-parsed visual aid), which means that the relationship between a key and its containing table exists only in the section header, not in the physical layout of the file. For deeply nested configurations, this makes TOML files harder to scan and harder to edit confidently.

What YAML 1.2 changed

The YAML 1.2 specification was published in 2009, with a clarifying revision (1.2.2) completed in October 2021.¹² Its changes address the complaints described above directly.

The implicit typing that created the Norway problem is gone. In the YAML 1.2 Core Schema, only true and false (and their capitalizations True, False, TRUE, FALSE) are recognized as booleans. The words yes, no, on, off, y, and n are plain strings. Sexagesimal number literals (the 22:22 problem) are removed entirely. Timestamp is no longer a core type, so an unquoted 2026-05-05 is a string under the core schema rather than an automatically detected date. JSON is now a strict, proper subset of YAML 1.2, which means any valid JSON document parses identically as YAML. The tag resolution rules are tightened and clarified. The specification itself, while still substantial, is written more clearly and maintained openly on GitHub.

In short, the YAML that people complain about is YAML 1.1. The specification that actually governs the language today is a different, safer, more predictable document. The problem is that most people’s experience of YAML is mediated not by the specification but by their parser, and for most Python users, that parser has been PyYAML, which implements YAML 1.1 and has not changed its core semantics since 2006.

The Python YAML parser landscape

PyYAML, written by Kirill Simonov in 2006, is the de facto standard YAML library in Python. It wraps LibYAML (a C library) for performance and provides a pure-Python fallback. It is downloaded millions of times per week, it is a dependency of countless packages, and it implements YAML 1.1. This last fact is the root of most YAML complaints in the Python ecosystem. When someone says “YAML parsed my country code as a boolean”, they are describing PyYAML’s behavior, not YAML’s specification. PyYAML’s GitHub repository shows over 200 open issues and 100 open pull requests.¹³ The project is maintained but moves slowly, and a major version bump to YAML 1.2 semantics has not materialized.

The ruamel.yaml library, maintained by Anthon van der Neut, offers YAML 1.2 support with round-trip preservation of comments, flow style, and key order.¹⁴ It is widely used and is significantly more capable than PyYAML for tasks requiring comment preservation or format-aware editing. However, it is primarily a pure-Python implementation in its default round-trip mode, which makes it considerably slower than PyYAML’s C-backed fast path. Its packaging history has also been complicated: namespace package issues and a dependency chain that has occasionally confused deployment pipelines.

StrictYAML takes a different approach entirely, implementing a deliberate subset of YAML with all implicit typing removed, no tags, no anchors, and no flow style.¹⁵ Philosophically it is closer to TOML than to full YAML: a safe, simple format that happens to use YAML’s indentation syntax. It is Python-only, has no implementations in other languages, and does not aim for spec compliance.

What has been missing from this landscape is a library that is fast, fully 1.2-compliant, and simple enough to use as a drop-in replacement for PyYAML’s basic interface.

Introducing py-yaml12

The py-yaml12 library is a YAML 1.2 parser and formatter for Python, implemented in Rust for speed and correctness. It is built on the saphyr crate¹⁶ (a Rust YAML library) and exposes a minimal, focused API: parse_yaml() and read_yaml() for loading, format_yaml() and write_yaml() for serialization.

Simple

The design philosophy is straightforward. For the vast majority of use cases, you work with plain Python builtins end to end: dict, list, int, float, str, and None. There is no special document class, no custom node types in the common path. Because YAML 1.2 is a superset of JSON, all valid JSON parses identically. The library achieves 100% compliance with the yaml-test-suite,¹⁷ the community-maintained corpus of edge cases and conformance tests.

from yaml12 import parse_yaml, format_yaml
from rich.pretty import pprint

config = """
server:
  host: 0.0.0.0
  port: 8080
  debug: false

database:
  url: postgres://localhost/mydb
  pool_size: 5

regions:
  - us-east-1
  - eu-west-1
  - no         # Norway, not false
"""

data = parse_yaml(config)
pprint(data)

{
│   'server': {'host': '0.0.0.0', 'port': 8080, 'debug': False},
│   'database': {'url': 'postgres://localhost/mydb', 'pool_size': 5},
│   'regions': ['us-east-1', 'eu-west-1', 'no']
}

Notice the no in the regions list. Under PyYAML (YAML 1.1), this would silently become False. Under py-yaml12 (YAML 1.2), it is the string "no", as the specification requires. This single behavioral difference encapsulates the entire argument: the format is not broken, the old tooling was.

The file API is similarly direct:

from yaml12 import write_yaml, read_yaml

path = "config.yaml"
write_yaml(data, path)

The round-trip is lossless. Writing a Python dictionary to disk and reading it back produces an identical object:

round_tripped = read_yaml(path)
assert round_tripped == data

print(f"Round-trip matches: {round_tripped == data}")

Round-trip matches: True

For advanced YAML features like tagged values, py-yaml12 provides the Yaml wrapper type. It is opt-in and unnecessary for typical configuration work.

Safe

The defaults in py-yaml12 are not just about ergonomics and simplicity; they also improve safety. PyYAML shows the risk of the opposite approach: treating tags as instructions can execute arbitrary Python code simply by reading a YAML file.¹⁸

For example, someone can produce a YAML file that aliases PyYAML’s Python object-apply tag namespace:

dangerous_yaml = """\
%TAG !py! tag:yaml.org,2002:python/object/apply:
--- !py!builtins.eval
- "(__import__('os').environ.__setitem__('YAML_PAYLOAD_RAN', '1'), {'debug': False, 'retries': 3})[1]"
"""

with open("dangerous.yaml", "w") as f:
    f.write(dangerous_yaml)

Then a user expecting only to load a config file runs that code during parsing:

import yaml

with open("dangerous.yaml") as f:
    data = yaml.load(f, Loader=yaml.Loader)

print(data)

{'debug': False, 'retries': 3}

The yaml.load() call looks like ordinary data loading: it returns an ordinary dictionary. But producing that dictionary executed Python code first. Unless you inspect the YAML itself, nothing in the result tells you that happened.

import os

os.environ["YAML_PAYLOAD_RAN"]

'1'

In contrast, py-yaml12 keeps an unhandled tag as data unless you explicitly opt in:

from yaml12 import read_yaml

read_yaml("dangerous.yaml")

Yaml(value=["(__import__('os').environ.__setitem__('YAML_PAYLOAD_RAN', '1'), {'debug': False, 'retries': 3})[1]"], tag='tag:yaml.org,2002:python/object/apply:builtins.eval')

Fast

Performance is a practical concern for any library that might be called in startup paths or CI pipelines. The py-yaml12 benchmarks¹⁹ compare read and write performance against PyYAML (both its default pure-Python path and the fast CSafeLoader/CSafeDumper backed by LibYAML) and ruamel.yaml, across file sizes ranging from kilobytes to megabytes. Because the core parsing and formatting logic is implemented in compiled Rust rather than interpreted Python, py-yaml12 is competitive with PyYAML’s C extension while maintaining full 1.2 compliance. As of this writing, few other Python libraries offer both.

Conclusion

The YAML-versus-TOML debate, as typically conducted, is an argument against a format that no longer exists in its problematic form. The complaints are real, but they are historical. They describe YAML 1.1 as mediated by PyYAML, not YAML 1.2 as specified and now properly implemented. TOML remains a good choice for shallow, flat configurations, and pyproject.toml is well-suited to its role. But the claim that YAML is inherently unsafe or unpredictable does not hold against a compliant 1.2 parser.

This is, in the end, a familiar pattern in computing. Every generation of configuration format is a correction of the previous generation’s excesses: INI was too flat, so XML added hierarchy; XML was too verbose, so JSON stripped it bare; JSON was too austere for humans, so YAML and TOML each offered different compromises. The interesting question is never “which format is best in the abstract” but “which format, with which tooling, serves this particular task well”. For complex, nested, human-authored configuration, YAML 1.2 with a modern parser is a strong answer. Perhaps in another decade, something new will arise to correct YAML’s remaining rough edges, and the cycle will continue. That is how formats improve.

In the meantime, you can pip install py-yaml12 and see what a modern, spec-compliant YAML experience looks like in Python.

And if you work in R, the r-yaml12 package brings the same benefits: full YAML 1.2 compliance, Rust-backed performance, and safe defaults. Everything good about the Python package is in the R version as well.

With the release of v0.10.0, we have reached a nice, round number and it’s worth looking back and surveying all the things that were done! So what follows is a survey of ten features (one per release) that represent the range of what Great Docs has become. Taken together, they tell the story of a documentation generator that starts simple and scales with your ambitions.

1. Auto-Discovery

The original release (v0.1) came out with the feature that defines the project’s philosophy. When you run great-docs init, Great Docs inspects your package and discovers its public API automatically. It finds classes, functions, dataclasses, protocols, enumerations, exceptions, type aliases, and more, using a combination of runtime introspection and static analysis via griffe. It detects your docstring style (NumPy, Google, or Sphinx) and writes a great-docs.yml configuration file that captures the full structure of your API.

reference:
  sections:
    - title: Core
      contents: [MyApp, Config, build, preview]
    - title: Utilities
      contents: [parse, validate, format_output]
    - title: Exceptions
      contents: [ConfigError, BuildError]

The practical consequence is that you don’t have to enumerate your exports by hand. If you add a new class or function to your package, the next build picks it up. If you remove something, it disappears from the site. The configuration file exists so you can reorder sections, add display names, or exclude internal symbols, but the default is complete and correct without any having to do any manual intervention.

This was the design decision that everything else built on: if Great Docs can figure something out automatically, it should, and configuration should be for expressing preferences rather than providing information that we could have inferred.

2. SEO and Proofreading

The v0.2 release added two capabilities that address different aspects of the same problem: making sure people can find your documentation and making sure what they find reads well.

On the discoverability side, Great Docs now generates sitemap.xml, robots.txt, canonical URLs, and JSON-LD structured data automatically. Per-page Open Graph meta tags are injected so that when someone shares a link to your documentation, the preview card shows a title, description, and image rather than a generic URL. The great-docs seo audit command checks your site for common problems (e.g., missing descriptions, broken canonical links, orphaned pages, etc.).

great-docs proofread

On the quality side, the great-docs proofread command runs local grammar and spelling checks powered by Harper, a fast grammar checker that runs entirely on your machine. It skips code blocks and YAML frontmatter, ships with a technical dictionary so it does not flag standard programming terms, and supports project-specific custom dictionaries for your package’s terminology. The output is available as plain text or JSON (which is well-suited for CI pipelines).

The combination means that documentation sites built with Great Docs tend to surface well in search results and tend to read cleanly once readers arrive. Neither of these things sound all that exciting, but both matter more than a lot of visual features.

3. Documentation Linting

Release v0.3 introduced great-docs lint, a static analysis tool for your documentation rather than your code. It inspects your package’s public API and checks for problems that would otherwise surface only when a user encounters a confusing or broken page.

great-docs lint

The linter catches missing docstrings (a function exists in your API but has no documentation), broken cross-references (you reference MyClass.process but the method is actually called MyClass.run), style mismatches (you declared NumPy-style docstrings but a function uses Google style), and unknown directives in your docstrings. It produces machine-readable JSON output, making it straightforward to add a lint step to your CI pipeline that fails the build when documentation quality degrades.

This sort of feature is more useful than you’d expect. You might run it, discover three functions that never got docstrings and two cross-references that broke during a refactor, fix them, and then feel quite happy. Using it again and again will probably prevent the same sort of problems from recurring. The goal is that no user should ever land on an API reference page and find it empty or confusing because of some oversight.

4. Internationalization

Great Docs v0.4 made it possible to present your entire documentation site in any of 23 languages with a single configuration option. The actual content of your pages remains in whatever language you write it in (usually English), but every piece of UI text (navbar labels, button tooltips, relative timestamps, search placeholders, accessibility attributes, pagination controls) is automatically translated.

site:
  language: fr

That single line transforms every “Next page” into “Page suivante”, every “Search” into “Rechercher”, and every “2 days ago” into “il y a 2 jours”. Translations include proper plural forms for languages that need them (like Polish, which has three plural forms depending on the number) and localized date expressions.

The reasoning behind this feature is straightforward: if your package has international users (and most packages do, whether they realize it or not), the friction of navigating a site where every label is in a language you do not speak fluently is real. While translating content is a large undertaking, translating UI chrome is something a tool can do for you.

5. Keyboard Navigation

The v0.5 release added a full keyboard shortcut layer that ships with every documentation site. Press / or s to focus search. Press [ and ] to navigate to the previous or next page. Press d to toggle dark mode. Press c to copy the current page as Markdown. Press h or ? to see a help overlay listing all available shortcuts.

All shortcuts are disabled when a text input has focus (so typing in search does not trigger navigation) and respect prefers-reduced-motion for users who have requested reduced animation. The system is enabled by default and can be disabled entirely via keyboard_nav: false in the configuration for projects that don’t want it.

Keyboard navigation is one of those features that, once you have used it for a day, makes every site without it feel slightly slower. The ability to browse through a long user guide using [ and ] without moving your hands to the trackpad is a small daily improvement that compounds over time. It also makes the sites more accessible to users who navigate primarily or exclusively by keyboard.

6. Page Tags and Status Badges

Release v0.6 introduced page-level metadata that surfaces in both the page body and the sidebar, giving documentation sites a lightweight content management layer.

Page tags let you categorize pages by topic using YAML frontmatter:

tags: [Configuration, Theming, Advanced]

Great Docs renders these as pill-shaped links above the page title and auto-generates a tags index page listing all tags across the site with links to their associated pages. If you maintain a large user guide with dozens of pages, tags give readers an alternative navigation path: instead of scrolling through the sidebar, they can click a tag to find all related content. Every User Guide page on the Great Docs site uses page tags, and the Page Tags guide explains how to set them up.

Page status badges mark pages with lifecycle states:

status: beta

The supported statuses are new, beta, deprecated, and experimental, each rendered as a color-coded badge below the page title. In the sidebar, these appear as compact icons so that readers can see at a glance which parts of the API are stable and which are still evolving. Status badges are automatically translated for non-English sites (the same i18n system from v0.4 applies) and include built-in Lucide icons and color schemes.

Together, tags and status badges give documentation authors a way to communicate structure and maturity without writing prose about it. A reader landing on a page immediately knows whether it describes a stable feature or an experiment, and can navigate to related topics through shared tags. The Page Status Badges guide covers the full set of options.

7. Scale-to-Fit

Great Docs v0.7 introduced a solution to a problem that plagues documentation for data-oriented packages: wide tables and HTML widgets that overflow the content column. When a table produced by Great Tables or a Pandas DataFrame is slightly wider than the page, the reader has to scroll horizontally to see a sliver of remaining content, which is a frustrating experience. But when content is dramatically wider than the container, shrinking it would make text unreadably small. So, in essence, different situations demand different responses.

Scale-to-Fit handles both cases. It automatically shrinks targeted elements so they fit within the container width, and falls back to horizontal scrolling when the element would need to shrink beyond a configurable minimum threshold. The default threshold is 60% of natural size, meaning content will shrink up to 40% to avoid scrollbars, but anything more extreme gets a scrollbar instead.

scale_to_fit: true
scale_to_fit_min_scale: 0.6

The feature can be enabled globally (all rendered HTML output gets the treatment), per-page via frontmatter, or manually on individual elements using a :::{.scale-to-fit} div wrapper. The global setting is what most data-oriented packages want: turn it on once and every GT table, every DataFrame display, and every custom widget in your documentation adapts gracefully to the reader’s viewport without any per-page configuration. The Scale-to-Fit guide demonstrates the behavior at different widths.

8. Versioned Documentation

Release v0.8 addressed a fundamental challenge of maintaining documentation for evolving libraries: users on older releases need docs that match the version they have installed. Great Docs makes multi-version documentation a build-time concern rather than a deployment concern. You declare your versions in configuration, and the build system produces a coherent, version-aware site.

versions:
  - "0.3"
  - "0.2"
  - "0.1"

That configuration produces three independent copies of your site: the latest version at the root URL, and previous versions under /v/0.2/ and /v/0.1/. A version selector dropdown appears in the navbar, letting readers switch between versions. Each version can reference an api_snapshot to regenerate API pages from that release (rather than the current code), and pages can use versions frontmatter to declare which releases they apply to. Pages that did not exist in older releases are automatically excluded from older builds.

The system also supports prerelease versions (marked in the dropdown but not served as “latest”), end-of-life versions (visually distinguished), and floating URL aliases like /v/stable/ that always resolve to the current release. Maintainers declare versions once and the build handles the rest. The Great Docs documentation site itself is a good example of this feature in practice: its version selector currently contains ten versions, one for each release from v0.1 through v0.10.0. The Versioned Docs guide covers the full configuration in detail.

9. Color Swatches

Great Docs v0.9 added a shortcode for documenting color palettes interactively. If your package has a theming system, a set of brand colors, or a palette of status indicators, you have probably faced the problem of showing colors in documentation. Screenshots go stale, hand-coded HTML swatches are tedious, and plain text hex codes are meaningless without a visual reference. The color-swatch shortcode turns a YAML file into an interactive palette.

Each swatch displays its hex code, shows RGB and HSL breakdowns on hover, evaluates WCAG and APCA contrast ratios against white and black backgrounds, and lets readers copy the color value with a single click. Two display modes are available: circles (compact, scannable) and rectangles (detailed, with contrast information front and center). Great Docs also ships with built-in presets for its own gradient themes, so you can reference preset="sky" or preset="lilac" without creating a YAML file at all.

For packages that deal with color (charting libraries, design systems, theming frameworks), this feature eliminates a category of maintenance burden. The YAML file is the source of truth; the rendered output is always current, always interactive, and always accessible. The Color Swatches page in the User Guide covers the full range of options.

10. Table Previews and Table Explorer

The most recent release, v0.10.0, added two complementary tools for embedding data directly in documentation pages. If your package works with tabular data (and many Python packages do), showing what a dataset looks like is one of the most common documentation tasks, and also one of the hardest to do well with static publishing.

tbl_preview() generates a self-contained, JavaScript-free HTML table from almost any data source:

from great_docs import tbl_preview

tbl_preview("data/example.parquet")

It accepts Polars DataFrames, Pandas DataFrames, PyArrow Tables, CSV files, Parquet files, and plain Python dictionaries. Each preview includes a colored type badge identifying the source format, compact dtype labels beneath every column header, row-number gutters, automatic head/tail splitting for large tables (showing the first and last rows with an ellipsis in between), and missing-value highlighting. The output works identically in light and dark modes and requires no JavaScript at all.

tbl_explorer() is the interactive counterpart. It embeds all data as inline JSON and progressively enhances a static fallback table with sorting, token-based filtering, pagination, column toggling, copy-to-clipboard, and CSV download. A Quarto shortcode variant lets you embed an explorer directly in a .qmd page by pointing at a data file, without writing any Python.

The distinction between the two is deliberate. tbl_preview() is for showing what data looks like: schema, types, a representative sample. tbl_explorer() is for letting readers interact with data: sort columns to find extremes, filter rows by values, hide irrelevant columns, and export subsets. Together they cover the full spectrum of data documentation needs, from a quick “here is the structure of this DataFrame” to a fully explorable reference dataset. The User Guide has dedicated pages for Table Previews and Table Explorer; the latter is worth visiting just to try the interactive tables yourself and see how sorting, filtering, and column toggling feel in practice.

What Ten Releases Add Up To

Looking back across ten releases, what is striking is not any single feature but the range of concerns the tool now addresses. Documentation generation is the starting point, but the problems that come after generation (discoverability, quality, accessibility, internationalization, versioning, interactivity) are where most of the ongoing work has gone. A documentation site is not just a rendering of your docstrings; it is a product that needs search engine optimization, proofreading, linting, keyboard accessibility, responsive design, and support for readers across languages and connection speeds.

The guiding principle remains the same as it was in v0.1: you should be able to get a good site with minimal effort! But “minimal effort” scales so, for a new package, that means three commands and zero configuration. For a mature package with international users, multiple supported versions, and extensive user guides, it means a great-docs.yml file that declares your preferences while the tool handles the mechanics of producing a site that meets the standard you have set.

Great Docs is available on PyPI so if you maintain a Python package and want to try it:

pip install great-docs
cd your-python-project
great-docs init
great-docs build
great-docs preview

The documentation site covers everything discussed here and much more. If there is a feature you wish your documentation site had (something that would save you time, help your readers, or make maintenance less painful), we would genuinely like to hear about it. The best ideas for the next ten releases will come from people who use the tool daily and notice what is missing. Open an issue on GitHub with your idea, however rough, and we will take it seriously!

Shared memory across processes is standard in other programming languages. In R it’s been either platform-specific (fork on Unix-alikes, unsafe from GUIs like Positron or with multi-threaded code) or file-format-specific (memory-mapped Parquet).

Two CRAN releases address those constraints directly:

• mirai 2.7.0 — daemons(memory = ...) puts a hard byte-level cap on the dispatcher queue. try_mirai() returns NULL immediately when that cap is hit, instead of blocking your session. The dispatcher itself runs as an in-process thread now; and through nanonext 1.9.0 underneath, peak memory during serialized sends has halved.
• mori 0.2.0 — graduates from experimental status, with a stable wire format underneath. Sub-lists and extracted elements now expose stable path-form names (/mori_abc[2,3]) that any process can attach to via map_shared() directly, without going through the parent.

Building out the foundations

mirai already shipped a lot of what production async needs: microsecond round-trip latency, FIFO scheduling, task cancellation, OpenTelemetry tracing, reproducible parallel RNG, custom serialization for torch / Arrow / polars, an event-driven promises method for Shiny ExtendedTask, and deployment across SSH / Slurm / Posit Workbench.

What these releases add is more foundational. R hasn’t really had a built-in memory model for asynchronous work — no way to size a task queue in bytes, and no portable way to share data across processes without paying for a full copy. mirai 2.7.0 introduces the first: a bounded queue built into the dispatcher, with try_mirai() exposing non-blocking submission under this constraint. mori 0.2.0 brings the second to a stable footing: a self-describing shared-memory format, addressable down to individual list elements by name, that any process on the machine can attach to.

Together they extend what R can credibly be used for — streaming pipelines, multi-stage data flows, and event-loop applications that previously had to reach outside the language.

mirai 2.7.0 — bounded queues and try_mirai()

daemons(memory = ...)

The dispatcher is the single point in your session where every mirai() call lands before being routed to a daemon. Each call carries its serialized arguments — the queued payload — and that payload sits in memory until a daemon is ready for it. By default the queue is unbounded, which is fine until it isn’t.

daemons() now takes a memory argument that caps the approximate total payload of queued tasks at the dispatcher, in MB:

library(mirai)
daemons(4, memory = 100)  # 100 MB queue capacity

When the queued bytes are below the cap, mirai() calls submit normally. When the cap is reached, mirai() blocks the calling R thread until daemons drain the queue enough for the new payload to fit. Existing code keeps working — the only visible difference is that your session can no longer be pushed out of memory by a runaway producer.

status() surfaces current and peak usage:

status()$memory
#     used     peak capacity 
#     12.4     87.3    100.0 

peak is the high-watermark queued payload over the lifetime of the dispatcher, which gives you an empirical way to size the cap. The recommended workflow is to run a representative workload with memory = NULL first (where capacity reports NA), observe peak, then set memory at or above that watermark.

If profiling isn’t practical, the local machine has to fit your session, the dispatcher queue, and n daemon processes (each a full R session holding an in-flight payload while executing). Half of currently available RAM (ps::ps_system_memory()[["avail"]] / 2e6, in MB) is a reasonable starting memory cap, revised down for large n or payloads. Remote daemons don’t draw on the local budget, so when most workers are remote, the cap can be more generous.

For n itself, one less than your number of CPU cores is the right starting point for CPU-bound work (one core left for your session), while I/O-bound work (API calls, database queries, file reads) can comfortably exceed core count since idle daemons cost little.

The capacity is measured in bytes, not task count. A queue capped at 100 tasks can hold either 100 small tasks or 100 huge ones, and only the second runs out of memory. A queue capped at 100 MB never runs your session out of memory regardless of the mix.

try_mirai()

A blocking submit is fine in a batch script, but not an event loop: a Shiny session that calls mirai() from inside an ExtendedTask can’t afford to block while the queue drains, because that same session is also driving the UI for all users.

try_mirai() returns immediately when the queue is full, instead of blocking. The semantics are simple:

• If the queue is below capacity, behaves identically to mirai() and returns a mirai.
• If the queue is at capacity, returns NULL immediately without blocking, and leaves the caller to decide what to do next.

m <- try_mirai({ slow_thing() }) %||% stop("queue full")

The three response strategies are: drop the task (best when the work is idempotent and frequent), retry later (queue the request behind a later::later() call), or propagate backpressure upstream — as in the example above, by raising a condition. Which is right is application-specific — try_mirai() hands you the flexibility.

If memory isn’t set, or the daemon configuration has no dispatcher, try_mirai() always returns a mirai and is identical to mirai() — so the function is safe to use unconditionally; it only does anything different in the bounded-queue case.

The two halves — daemons(memory = ...) and try_mirai() — are the right combination for any event-loop integration. Set the cap to reflect what your session can actually afford to hold, submit through try_mirai(), and the application gracefully adapts to load instead of locking up or crashing.

Under the hood

A few transport-layer changes ship alongside 2.7.0 — invisible most of the time, important when payloads are large or throughput is high:

• Dispatcher as a thread. The dispatcher is no longer a separate R process; it runs as an in-process thread, courtesy of a C-level reimplementation in nanonext. mirai round-trip latency is now in the tens of microseconds.
• Halved peak memory on sends. nanonext 1.9.0, the transport underneath mirai, now writes serialized sends directly instead of going through an intermediate buffer. A 500 MB argument going to a daemon used to need ~1 GB of momentary headroom in your session; now it needs ~500 MB. The dispatcher’s actual resident memory tracks the daemons(memory = ...) cap more accurately as a result.
• >2 GB payloads on macOS and Windows. Transfers above 2 GB previously failed silently near the INT_MAX-byte boundary on those platforms. They now go through cleanly. Linux was already fine.

mori 0.2.0 — out of experimental status

mori is a younger package — its first CRAN release was just last month — and its job is the other half of memory pressure: the data itself, rather than the queue. R processes don’t share memory, and data crosses between them through message-passing. When eight workers each need the same 200 MB data frame, that’s 1.6 GB of serialize / transfer / deserialize, plus eight separate copies of the data resident in RAM.

mori::share() writes the object once into OS-level shared memory and returns an ALTREP (alternative representation) wrapper. Multiple processes on the same machine map the same physical pages — zero-copy, lazy, and managed by R’s garbage collector. Pass the wrapper to a daemon and only the shared memory identifier (hundreds of bytes) crosses the wire; the daemon attaches and reads the pages directly.

We implemented this in mori 0.1.0, but 0.2.0 takes mori out of experimental status, landing a stable wire format. A key consequence of this is that every sub-list and extracted element of a shared region now has a stable identifier of its own. shared_name() emits path-form names (/mori_abc_1[2] for the second element of region /mori_abc_1, /mori_abc_1[2,3] for nested addressing), and map_shared() accepts the path form directly.

library(mori)
library(mirai)

lst <- share(
  list(weights = rnorm(1e6), targets = rnorm(1e6), inputs = rnorm(1e6))
)

# Sub-elements have their own path-form names

shared_name(lst)
#> [1] "/mori_abc_1"
shared_name(lst[[1]])
#> [1] "/mori_abc_1[1]"

Pass the shared object directly to a daemon — the ALTREP wrapper serializes as just the name, and the daemon attaches on deserialize:

mirai(length(weights), weights = lst[[1]])[]
#> [1] 1000000

A consumer in a separate session that only has the name as a string — from a config file, message queue, or HTTP response — attaches with map_shared():

# In a separate R session

weights <- mori::map_shared("/mori_abc_1[1]")
length(weights)
#> [1] 1000000

A path-form name is a small thing on the wire – just a string – but it enables a lot:

• Attach by name. Path-form identifiers are plain strings, so they fit anywhere a string can go: a queue payload, a config entry, an HTTP response, a database row. A consumer reads the name, calls map_shared(), and gets exactly that slice — the parent region never has to enter their session.
• Decoupled pipelines. Stage A shares a 100-column frame and tells stage B the names of the three columns to process. Stage B passes the name of its output to stage C, and so on. No stage holds more in memory than it actually uses, and no stage needs to know how its inputs were produced — only the names.
• Code symmetry. map_shared(shared_name(x)) returns an equivalent of x whether x is a root region or a single leaf element, so consumer code doesn’t need a special branch for sub-objects.
• Lifetime through one chain. Holding a reference to a leaf keeps the whole parent region alive automatically — the garbage collector walks the chain of dependencies — so a consumer never has to manually pin the root to stay safe.

Composing with daemons(memory = ...)

The two memory tools compose. mori::share() shrinks each task’s queued payload from megabytes to hundreds of bytes, which means the dispatcher’s memory cap rarely fills up at all when workers are reading shared data. The pieces are complementary:

• mori::share() removes the per-worker copy of large data.
• daemons(memory = ...) caps the dispatcher backlog when something is being sent.
• try_mirai() makes hitting that cap a non-event in an event loop.

Putting R on the concurrency map

The design of daemons(memory = ...), try_mirai(), and mori::share() draws on how async runtimes in other languages handle the same problems. Here’s the comparison:

Byte-budgeted backpressure. Async frameworks elsewhere — Python’s asyncio.Queue, Ray’s max_pending_tasks, Tokio’s bounded mpsc channels — measure queue capacity by task count. daemons(memory = ...) caps by bytes instead, which tracks what actually drives memory pressure.

Non-blocking submission on a full queue. Tokio’s try_send is the closest direct analogue: it returns immediately when the channel is full instead of blocking. try_mirai() provides the same semantics for R submission, with the additional advantage that the cap itself is byte-aware.

Integrated cross-process zero-copy. Ray’s Plasma object store offers cross-process zero-copy, but it’s a heavyweight component — you run a Ray cluster to use it, not a function. mori::share() is just a function call, producing an ALTREP wrapper that consumer processes attach to via lazy reads, down to individual columns by name.

Combined with mirai’s microsecond round-trip latency and event-driven C-level transport, these three pieces give R a concurrency story that stands on its own: byte-aware backpressure, non-blocking submission, and integrated zero-copy sharing.

Try it

Install from CRAN:

install.packages(c("mirai", "mori"))

Pointers from here:

• mirai reference vignette — the memory-management section walks through daemons(memory = ...), status()$memory, try_mirai(), and shared-memory composition.
• mirai promises vignette — Shiny ExtendedTask and event-driven async.
• mori package site — share(), shared_name() and map_shared().
• nanonext package site — the transport layer and concurrency primitives.
• The r-lib agent skill in the posit-dev-skills plugin includes an LLM-optimised mirai guide for AI coding assistants.

Issues, feedback, and questions are very welcome on GitHub: r-lib/mirai, r-lib/nanonext, shikokuchuo/mori.

Acknowledgments

A big thanks to everyone who contributed to mirai 2.7.0, mori 0.2.0, and nanonext 1.9.0 through their issues, pull requests, and discussions: @HenrikBengtsson, @kentqin-cve, @king-of-poppk, @manforkr, @mcol, @michaelmayer2, @pmac0451, @t-kalinowski, and @wlandau.

Welcome back to another edition of our monthly Positron updates! Each month we share highlights from our latest release and useful resources.

Product updates

Announcing the Packages pane

Our Packages pane is available in this release as a preview feature. The new Packages pane brings streamlined package management directly into the IDE so you can see at a glance what’s installed, what’s attached, and what’s out of date.

Find it in the Primary Sidebar by clicking the package icon. Positron automatically detects and integrates with your current interpreter; today we have support for pip, venv, uv, and conda for Python, plus base R, pak, and renv for R. You can search, sort, install, update, remove, filter by category (including “Outdated Packages”), and even see which packages are attached in your current session. To hide the pane, disable positron.packages.enable. Let us know how it fits into your workflow.

Inline output for Quarto

Inline output for .qmd documents was one of Positron’s most-requested features ever, with many users telling us it was the one thing keeping them tied to RStudio or Jupyter notebooks. We are happy to share that Quarto inline output is available this release as a preview feature.

Quarto kernels start automatically when you open a document with inline output, so you don’t wait for a kernel on first execution. Each inline output cell shows a status line with execution status and elapsed time, and outputs are now collapsible when they get long. We’ve also added a tool to switch the interpreter used for inline output, support for Show Notebook Console for Quarto documents, and fixed a handful of papercuts around execution indicators, autocompletion, and the kernel selector. Enable inline output via the positron.quarto.inlineOutput.enabled setting.

Extensions available from Posit Public Package Manager

Positron’s extension gallery now uses Posit Public Package Manager (P3M) by default, replacing Open VSX as the source for browsing and installing extensions. The catalog is the same set of extensions you already use, served from Posit infrastructure for reliable distribution. If you prefer to stay on Open VSX, the new positron.extensions.gallerySource setting lets you switch back at any time. For organizations on Posit Workbench, Posit Package Manager also added support for mirroring and serving VS Code extensions from your own instance, bringing the same governance, security, and air-gapped distribution to extensions that you already have for R and Python packages.

Positron Notebook Editor is now in beta

The Positron Notebook Editor for .ipynb files is officially moving from alpha to beta.

This release brings a wave of polish and reliability we hope makes it ready for your daily workflow:

• Cleaner git diffs by default: New notebook.save.outputs and notebook.save.executionCounts settings let you exclude outputs and execution counts from saved notebook files so reviewers see only the relevant code changes.

• Stronger R support: R notebooks can now be debugged with breakpoints and the “Debug Cell” action, and R dataframe outputs in notebook cells now render in the inline Data Explorer for the same interactive exploration you get in the Console.

• Help on F1: Pressing F1 on a function in a notebook cell now opens the Help pane, just like in .py and .R files. Works for both Python and R Jupyter notebooks.

• UX polish: Long cell outputs default to scrolling instead of overwhelming the page, the cell action bar stays visible as you scroll through tall cells, markdown cells render footnotes, and your scroll position is preserved when switching between notebook tabs.

AI chat and code assistance

This release introduces two new AI options: Posit Assistant and Posit AI.

• You may have tried some of our previous experiments for AI code assistance available in Positron, Positron Assistant and/or Databot. We are now migrating to a more data-science-specific, holistic, unified approach to AI chat, built on the same Posit Assistant interface that we recently brought to RStudio. We acknowledge that the number of different tools we’ve made available and how their names have evolved have been pretty confusing, but this space is changing fast and our initial experiments have helped us understand the best ways to integrate AI into your data science workflow. With Posit Assistant, instead of switching between tools, you get code generation, next edit suggestions, chat, and agentic tools all in one place. Learn how to get started.

• Posit AI is a new, optional model provider service available to use with Posit Assistant. Posit AI is a subscription priced at $20/month for individual users; both Positron and Posit Assistant remain free to use. Learn how to sign up for an account.

This release also provides additional improvements to the broader Assistant experience. Each Assistant response now shows which model generated it, so you always know whether you’re getting output from Claude, GPT-5, or another provider. We also improved the documentation and error handling for Microsoft Foundry and prompt caching for AWS Bedrock.

What’s coming next

• Last release, we announced Positron Server for academic use in JupyterHub, making it free to host Positron for teaching. We are now expanding support for Positron Server on Open OnDemand. If you are interested in using Positron for teaching, follow the instructions to get a teaching license and book time with our team to discuss your use case.
• We’re prototyping first-class SQL editing and execution in Positron, including support for visualizations with ggsql. We’ll share more as this takes shape, and in the meantime, let us know your thoughts and current pain points.
• Join our next webinar on May 12 to learn how Positron, Workbench, Connect, and Package Manager work together in the reproducible analysis lifecycle.