Deploy To Connect

<!--
Maintainer note: edit this skill in posit-dev/connect only.
Downstream copies are overwritten by the sync workflow.
-->

Deploying to Posit Connect

This guide covers Python and R content on a Posit Connect server. Work through the stages in order.

Two toolchains do the work:

• Python — rsconnect-python, which provides the rsconnect CLI and is published on PyPI.
• R — the R rsconnect package, pointed at a Connect server.

If the user asks a question ("how do I…", "what is the command…") rather than asking for a deploy, answer from this guide and stop.

At the end, report which server you deployed to, which content type you picked, any tool you installed, and any assumption you made.

Stage 1 — Detect the content

Infer the language and framework from the files in the project directory. Common signals:

Confirm the guess

The imports in app.py name the framework:

grep -Eo 'import (shiny|streamlit|dash|gradio|panel|bokeh)|from (shiny|streamlit|dash|gradio|panel|bokeh)' app.py

A bare ASGI or WSGI object means fastapi or flask.

Dependency files confirm the language: requirements.txt and pyproject.toml for Python, DESCRIPTION and renv.lock for R.

Quarto renders a script only if it opens with a front-matter comment: # %% [markdown] around a --- block in Python, #' --- in R. Most scripts lack one — add it before the deploy (Stage 5).

If the content is ambiguous (both Python and R files, or an app.py with no recognizable import), use your discretion, and report the assumption you made.

Stage 2 — Inventory your tools

Probe the environment and build a capability set:

command -v rsconnect                                 # rsconnect-python on PATH
command -v uv                                        # uv (installs and runs Python tools)
uv tool list 2>/dev/null | grep rsconnect            # rsconnect-python installed via uv
command -v Rscript                                   # R present
Rscript -e 'cat(requireNamespace("rsconnect", quietly=TRUE))' 2>/dev/null   # R rsconnect package
command -v quarto                                     # quarto CLI
command -v git                                        # git

With uv present, Python content needs no install step. uv tool run --from rsconnect-python rsconnect ... fetches and runs the CLI on demand.

Stage 3 — Pick a route

Cross the detected content (Stage 1) with your capabilities (Stage 2).

Python content

Use rsconnect-python. With rsconnect on PATH:

rsconnect deploy <framework> ./my-app

Off PATH but with uv present:

uv tool run --from rsconnect-python rsconnect deploy <framework> ./my-app

Both forms take identical arguments. The rest of this guide writes the bare rsconnect ... form. Prefix it with uv tool run --from rsconnect-python when you use the second route.

<framework> is one of api, bokeh, bundle, dash, fastapi, flask, git, gradio, html, manifest, nodejs, notebook, panel, pyproject, quarto, shiny, streamlit, tensorflow, voila. For anything outside that list, rsconnect deploy other-content prints guidance.

The frameworks and flags depend on the installed version, so confirm against rsconnect deploy --help rather than this list. If uv tool run resolves a stale cached version, pin it: uv tool run --from 'rsconnect-python==1.30.0' rsconnect ....

R content

Use the R rsconnect package, through Rscript -e '...' or an R session:

• Shiny for R, Plumber API, or any app directory → deployApp()
• A single R Markdown or Quarto document → deployDoc()
• A full R Markdown or Quarto site → deploySite()

If Rscript is absent, deploy the R content through rsconnect-python with a manifest.json:

• A manifest.json already exists — deploy it directly:

  rsconnect deploy manifest ./manifest.json

• No manifest, but R is available elsewhere — generate one first with rsconnect::writeManifest() (see Stage 5).
• Neither R nor a manifest — a valid R bundle is not possible. Surface this as a blocker: ask the user or report it clearly.

Quarto content

rsconnect deploy quarto ./report

R-flavored Quarto (a .qmd with R code chunks) needs R to render. If R is absent, treat the document as R content and use the manifest route, or surface the gap.

Script content

Use the quarto framework. Add the front matter first (Stage 5).

rsconnect deploy quarto script.py    # Python, rsconnect-python 1.23.0 or later

rsconnect::deployApp()               # R, rsconnect 1.2.2 or later, from the directory of the script

Both commands include every file in the directory. Push-button publishing does not cover R scripts, so deployApp() is the only R route.

A script deploys like a Quarto document but is a different content type: a .qmd is a page to read, a script is a job that writes output.

Stage 4 — Find the target and check its credentials

Now that the tool is known, find out which server to deploy to and whether the tool can already reach it. This is a check, not a login.

Do not search the environment for API keys. Do not read CONNECT_API_KEY, CONNECT_SERVER, a .env file, a keychain entry, or any other stored secret to pick a target or to register a server. Do this only when the user explicitly asks for it. An environment variable is not a request to use it.

List the accounts the tool already has. This is the only credential check you need.

rsconnect list                                   # Python: saved servers, stored tokens, and the default server on 1.30.0+
Rscript -e 'print(rsconnect::accounts())'        # R: registered accounts

If the tool is not installed yet, close that gap in Stage 5 first. Then run the check.

Compare the result with the target the user named. Three outcomes:

• An account matches the named target. The credential path is live. Run no login and no rsconnect add. Continue to Stage 6 once the other gaps are closed.
• The user named no target. Ask them. List the servers the check found, and ask which one to deploy to, or whether they want a new target instead. Do not pick one for them, and do not deploy to the only saved server because it is the only one.
• The target is new, or no account matches it. This is a gap for Stage 5. Register it with a browser login.

A browser login is the way to register a new target:

rsconnect login https://connect.example.com      # Python

rsconnect::addServer(url = "https://connect.example.com", name = "myserver")   # R
rsconnect::connectUser(server = "myserver")

Both forms open a browser flow, so the user approves the login and no key passes through the conversation. The credentials reference has the details and the pitfalls.

Stage 5 — Resolve gaps

When Stages 3 and 4 find a gap, close it, then include the action in your report.

rsconnect not on PATH. With uv present, no install is needed:

uv tool run --from rsconnect-python rsconnect deploy <framework> ./my-app

If the user wants it installed persistently, or uv tool run is not viable:

uv tool install rsconnect-python     # or: pip install rsconnect-python

The package name and the command name differ: the PyPI package is rsconnect-python, and the command it provides is rsconnect. That is why uv tool run needs --from rsconnect-python. To update later, run uv tool upgrade rsconnect-python.

R rsconnect package missing, Rscript present. Install it from Posit Package Manager (P3M), which serves precompiled Linux binaries. A binary install is much faster than a source build and needs no -dev system libraries. Binaries need two things: the __linux__/<codename> repo URL and a platform-identifying HTTPUserAgent. Without the user agent, P3M serves source.

export P3M="https://packagemanager.posit.co/cran/__linux__/$(. /etc/os-release && echo "$VERSION_CODENAME")/latest"
Rscript -e '
  options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(),
    paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))
  install.packages("rsconnect", repos = Sys.getenv("P3M"))
'

P3M binaries exist for x86_64 on common distros. On arm64 or an unsupported distro, P3M falls back to source. That result is still correct, only slower, and it needs the usual -dev libraries and a compiler. Use https://cloud.r-project.org (CRAN source) only when P3M is unreachable.

manifest.json missing for R content, R present. Generate it:

Rscript -e 'rsconnect::writeManifest()'

rsconnect-python writes one for Python content:

rsconnect write-manifest <framework> ./my-app

Then deploy the manifest with rsconnect-python if R cannot deploy directly.

Script front matter missing. Add the minimal block at the top of the file. Connect takes the content title from title, so write a descriptive one.

Python:

# %% [markdown]
# ---
# title: "Data processing script"
# ---

R:

#' ---
#' title: "Data processing script"
#' ---

No account for the target. Register it now with a browser login: rsconnect login for Python, or rsconnect::addServer() and rsconnect::connectUser() for R. The credentials reference has the details and the pitfalls. Do not fall back to an API key from the environment. If the browser flow is not available, report that and stop.

Dependencies. rsconnect and rsconnect-python scan the code and snapshot the required package versions for you, so hand-listing them is rarely necessary. Python content needs a requirements.txt. For R, the content's own packages must be installed locally for rsconnect to detect them — plumber for a Plumber API, shiny for a Shiny app. Install any that are missing from the same P3M repo shown above.

Stage 6 — Deploy and handle failure

Discover the live command surface (Python)

The frameworks and flags in rsconnect-python change between releases, and the help text is the source of truth:

rsconnect version                  # which version you are actually running
rsconnect deploy --help            # every framework you can deploy
rsconnect deploy <framework> --help  # flags for one framework

Deploy

For Python, run rsconnect deploy <framework> <dir> with the framework Stage 3 picked. The manifest framework takes the manifest file rather than a directory.

Non-obvious flags: -t/--title, -N/--new (force a new deployment instead of updating the recorded one), -a/--app-id <id> (target an existing item explicitly, mutually exclusive with --new), -E NAME=VALUE (set an environment variable, repeatable), --draft (keep serving the previous bundle until published).

For R, call the function Stage 3 selected. Pass appTitle so the content is not named after the directory.

A script deploy sweeps the whole directory. If the directory holds files the script does not need, narrow the selection: name the files in Python (rsconnect deploy quarto script.py helper.py data.csv) or pass appFiles in R (rsconnect::deployApp(appFiles = c("_quarto.yml", "script.R"))). A directory with a _quarto.yml is a Quarto project — deploy it whole with rsconnect deploy quarto ..