Publishing from the Command Line

Posit Connect supports the deployment of Jupyter Notebook, Python APIs (such as those based on Flask or FastAPI), and apps (such as Dash, Streamlit, Shiny for Python, and Bokeh apps).

Content types not directly supported by the CLI can also be deployed if they include a prepared manifest.json file. See the Deploying R or Other Content section for details.

You must configure your Connect account before attempting to publish using rsconnect-python. See the Installing section below for information on configuring your Connect account.

Installing

Install the rsconnect-python command line interface in the virtual environment for your project using pip:

pip install rsconnect-python

Once rsconnect-python is installed, the rsconnect command line utility is available in your python binaries directory. In many cases, it is on your PATH and accessible by executing rsconnect on the command line.

Adding a Connect server

A Connect server must be registered in order to use deploy commands.

To add a server, you need the following:

  1. Your server URL (--server/-s)
  2. Your API key (--api-key/-k). See the API Keys section.
  3. A nickname for the server that you provide (--name/-n)
rsconnect add \
    --server https://my.connect.server/ \
    --name myServer \
    --api-key $CONNECT_API_KEY

Once the server is added, rsconnect deploy commands can reference that server by using the -n or --name flag, followed by the nickname.

Using rsconnect-python

Use the rsconnect deploy command to deploy content to Connect. See the content-type specific documentation for details on the deployment commands and options available for various content types:

Package dependencies

If a requirements.txt file exists in the source directory, it will be included in the deployment bundle. It must specify the package dependencies needed to execute your Python code. Connect reconstructs the Python environment using the specified package list. Using a requirements.txt file gives you the most control over the packages that Connect installs to run your content. Using the same requirements.txt file across multiple deployments also allows Connect to reuse the corresponding Python virtual environments, making deployments faster.

If there is no requirements.txt file or the --force-generate option is specified, the package dependencies are determined from the current Python environment, or from an alternative Python executable specified via the --python option. For example:

rsconnect deploy api --python /path/to/python my-api/

You can see the packages list that will be included by running pip list --format=freeze yourself. Ensure that you use the same Python that you use to run your code. For example, if you have created a virtual environment for your project, activate the environment or specify the full path to the Python interpreter:

/path/to/python -m pip list --format=freeze

Python version matching

Connect requires matching <MAJOR.MINOR> versions of Python. For example, a server with only Python 3.10 installed will fail to deploy content created with Python 3.8. Your administrator can also enable exact Python version matching which is stricter and requires matching major, minor, and patch versions. For more information see the Python Version Matching section of the Admin Guide.

Deployment options

These options apply to any type of content deployment.

Title

The title of the deployed content is, by default, derived from the filename. For example, if you deploy my-notebook.ipynb, the title will be my-notebook. To change this, use the --title option:

rsconnect deploy notebook --title "My Notebook" my-notebook.ipynb

When deploying an API or application, the title is derived from the directory containing the API or application.

When using rsconnect deploy manifest, the title is derived from the primary filename referenced in the manifest.

Environment variables

You can set environment variables during deployment. Their names and values are passed to Connect during deployment so you can use them in your code.

For example, if notebook.ipynb contains

print(os.environ["MYVAR"])

You can set the value of MYVAR that is set when your code runs in Connect using the -E/--environment option:

rsconnect deploy notebook \
    --environment MYVAR='hello world' \
    notebook.ipynb

To avoid exposing sensitive values on the command line, you can specify a variable without a value. In this case, it uses the value from the environment in which rsconnect-python is running:

export SECRET_KEY=12345

rsconnect deploy notebook --environment SECRET_KEY notebook.ipynb

If you specify environment variables when updating an existing deployment, new values will be set for the variables you provided. Other variables remain unchanged. If you don’t specify any variables, all of the existing variables remain unchanged.

Environment variables are set on the content item before the content bundle is uploaded and deployed. If the deployment fails, the new environment variables still take effect.

Target image

If your Connect installation uses off-host content execution with Kubernetes, Connect automatically selects an appropriate image to use when building or running your content. However, you can also specify a different image by providing the image argument when writing a manifest or deploying:

rsconnect deploy api \
    --image "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy" \
    ...

rsconnect write-manifest api \
    --image "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy" \
    ...

You can only use an image that has been configured by your administrator. You can see a list of available images by logging in to Connect and clicking the Environments button at the top of the page.

If the image you select does not contain an appropriate Python version for the content you are deploying, the deployment will fail.

At any time, you can redeploy content without specifying an image (or write a manifest without specifying an image, and deploy the manifest) to go back to allowing Connect to choose an image automatically.

Note

The following subcommands do not support the --image argument:

rsconnect deploy html
rsconnect deploy manifest
rsconnect deploy other-content

Specifying an environment management strategy

Note

Note that the environment management features used in this guide are also applicable for Connect in local execution mode. Off-host execution is not required to use the Python and R environment management features.

Sometimes it is preferable to self-manage Python package installation for your system, rather than allowing Connect to install packages for you. This can be useful in situations where many pieces of content share the same set of packages, or if off-host execution is enabled and the packages are already installed in the execution environment image.

rsconnect deploy api --disable-env-management-py ...

rsconnect write-manifest api --disable-env-management-py ...

When environment management is disabled, Connect uses only the packages that are already installed in the system library. No new packages are installed during the deployment. It is up to your administrator to install the required packages in the system library so that they are available for your content at runtime.

At any time, you can redeploy content without specifying an environment management strategy (or write a manifest without specifying, and deploy the manifest) to go back to allowing Connect to choose an environment management strategy based on the application-level and server-level defaults specified by your server administrator.

Note

The following subcommands do not support the --disable-env-management flags:

rsconnect deploy html
rsconnect deploy manifest
rsconnect deploy other-content

Updating a deployment

If you deploy a file again to the same server, rsconnect will update the previous deployment. This means that you can keep running rsconnect deploy notebook my-notebook.ipynb as you develop new versions of your notebook. The same applies to other Python content types.

Forcing a new deployment

To bypass this behavior and force a new deployment, use the --new option:

rsconnect deploy dash --new my-app/

Updating a different deployment

If you want to update an existing deployment but don’t have the saved deployment data, you can provide the app’s numeric ID or GUID on the command line:

rsconnect deploy notebook --app-id 123456 my-notebook.ipynb

You must be the owner of the target deployment or a collaborator with permission to change the content. The type of content (static notebook, notebook with source code, API, or application) must match the existing deployment.

Note

No confirmation is required to update a deployment. If you do so accidentally, use the Source Versions dialog in the Connect dashboard to activate the previous version and remove the erroneous one.