Skip to main content

Scripts

Posit Connect supports rendering script files (e.g., .py, or .R). Scripts are rendered using Quarto, an open-source scientific and technical publishing system built on Pandoc. Script files must be specially formatted for Quarto to recognize and render them.

Note

Script rendering requires at least Quarto 1.4.

Scripts can be used for many different data processing purposes, including any of the following:

A standalone script can be deployed to Connect. Scripts can also be published to Connect within a Quarto project alongside other Markdown content.

Output produced by scripts is presented by Connect when you visit the content. The output may be simple text messages produced by the script, or may include formatted text, images, and interactive elements.

You can schedule the execution of scripts in Connect. Additionally, script files produce custom email when they produce an email Markdown block.

Prerequisites

Install these prerequisites into your development environment before running the examples on this page.

  1. Quarto 1.4 or newer.

  2. uv to manage the Python environment.

  3. A uv project with the Quarto Python requirements. In the directory for your scripts, create a project and add Jupyter:

    Terminal
    uv init --bare --python 3.12 --pin-python
    uv add jupyter

    Replace 3.12 with the Python version that your scripts use. See setting up your project for details.

  4. Packages used by the examples.

    Terminal
    uv add pandas
  5. Install the Posit CLI for deployment.

  1. Quarto 1.4 or newer.

  2. Quarto R requirements

    install.packages("rmarkdown")
  3. Packages used for deployment.

    # rsconnect 1.2.2 or higher is required.
    install.packages("rsconnect")

In order to deploy scripts, your Connect server must be configured with compatible versions of Quarto, Python, and R.

Simple example

These examples show some very basic script files that can be rendered by Quarto. They both construct random data and write a CSV file.

# %% [markdown]
# ---
# title: "Python script file"
# ---

# %%
import datetime
import pandas as pd
import random

# Randomly generate data that acts as 30-day trailing unit sales.
today = datetime.date.today()
data = pd.DataFrame({
    'Date': pd.date_range(
        today - datetime.timedelta(days=30),
        today - datetime.timedelta(days=1),
    ),
    'Sales': [random.randint(75, 100) for _ in range(1, 31)],
})


# Write a CSV for downstream use.
data.to_csv("sales.csv", index=False)

# %% [markdown]
# Download [CSV](sales.csv)
#' ---
#' title: "R script file"
#' ---

# Randomly generate data that acts as 30-day trailing unit sales.
today <- Sys.Date()
data <- data.frame(
  Date = today - 1:30,
  Sales = sample(75:100, 30, replace = TRUE)
)

# Write a CSV for downstream use.
write.csv(data, "sales.csv", row.names = FALSE)

#' Download [CSV](sales.csv)

When adapting existing scripts, you must add an initial front-matter comment:

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

See the Quarto documentation for additional syntax and examples.

Email example

These examples show how to produce custom email from a script file.

# %% [markdown]
# ---
# title: "Python script custom email"
# format: email
# ---

# %%
import random
choices = [ "red", "orange", "yellow", "green", "blue", "indigo", "violet" ]
choice = random.choice(choices)
choice

# %% [markdown]
# ::: {.email}
# ::: {.subject}
# Custom email from a Python script
# :::

# %%
#| echo: false
#| output: asis
print(f"Color of the day: {choice}")

# %% [markdown]
# :::
#' ---
#' title: "R script custom email"
#' format: email
#' ---

choices <- c("red", "orange", "yellow", "green", "blue", "indigo", "violet")
choice <- sample(choices, 1)
choice

#' ::: {.email}
#' ::: {.subject}
# Custom email from an R script
#' :::

#| echo: false
#| output: asis
cat("Color of the day: ", choice, "\n")

#' :::

Render and preview

You can render and preview notebook scripts from the command line, just as you would other types of Quarto content.

Depending on your configuration, you can preview and render an entire project or a specific file.

The Quarto render command runs the targeted content and writes the results to disk.

Render a single file:

Terminal
uv run quarto render script.py

Render a project:

Terminal
uv run quarto render

Render a single file:

Terminal
quarto render script.R

Render a project:

Terminal
quarto render

The Quarto preview command renders the targeted content and opens a browser to visit that content. Your content is refreshed after an edit.

Preview a single file:

Terminal
uv run quarto preview script.py

Preview a project:

Terminal
uv run quarto preview

Preview a single file:

Terminal
quarto preview script.R

Preview a project:

Terminal
quarto preview

Publishing

Deploy Python scripts from the command line using the Posit CLI.

Before publishing, install the Posit CLI and sign in to Connect.

You can deploy a script by itself:

Terminal
posit connect deploy quarto script.py

You can also deploy a script along with supporting files:

Terminal
posit connect deploy quarto script.py helper.py data.csv

When your script is part of a Quarto project having a _quarto.yml file, you can deploy the project directory:

Terminal
posit connect deploy quarto .

Each of these commands reads your package dependencies from a requirements.txt file in the same directory as the script or project. If the file does not exist, the command stops with an error. To create the file, export your project’s locked dependencies:

Terminal
uv export --no-dev --no-emit-project --no-hashes -o requirements.txt

See package dependencies for other options.

When you deploy a script file, posit connect deploy uploads only that file, any additional files you list, requirements.txt, and the generated manifest. It doesn’t include other files in the directory, so list every helper or data file that your script needs. When you deploy a directory, posit connect deploy considers all of the files in that directory.

For command arguments, see the posit connect deploy quarto reference.

R scripts are deployed from RStudio and the R console with the rsconnect R package. Unlike some other content types, push-button publishing is not available for R scripts.

Note

Use rsconnect 1.2.2 or higher when publishing scripts.

Before getting started, make sure that you have linked your Connect account from your R session. This only needs to be done once.

From the project directory containing your R script, use rsconnect::deployApp() to publish your script.

rsconnect::deployApp()

The call to rsconnect::deployApp() considers all of the files in the current directory when determining how to deploy them. If you are deploying a standalone R script, you probably want a directory containing only the script file or the script file with a _quarto.yml file. If your R script is contained in a directory with many other files, call deployApp() with the appFiles argument in order to control exactly which files to include.

rsconnect::deployApp(appFiles = c("_quarto.yml", "script.R", "helper.R"))

For additional details about appFiles and other arguments, see the rsconnect::deployApp() documentation.