Your first Python project in Positron

Prerequisites

Before you get started, you will need to download Positron and a Python interpreter. You can download Positron here. Learn more here.

Create or open a folder

The first step is to open a folder. Opening a folder creates a workspace in Positron, setting the working directory to the path of the folder.

You can either open an existing folder or create a new one. We’ll create a new folder for our Python project.

Click New folder, then select Python Project. Name the folder first-python-project, and select an appropriate location for the folder.

Check the box next to Initialize Git repository to set up a Git repository for your project. If you don’t use Git or don’t have it set up, you can skip this step.

Install packages

Now that your environment is active, the next step is to install the packages you’ll need for your project. For now, let’s install jupyter, pandas, and matplotlib.

Open the Terminal and run:

pip install jupyter pandas matplotlib 

To make your environment reproducible, create a requirements.txt file by running the following line in the Terminal:

pip freeze > requirements.txt

This file lists all packages in your environment and their versions. You (or a teammate) can recreate the environment later with:

pip install -r requirements.txt

Positron will also recognize if your folder contains a requirements.txt file and will automatically ask if you’d like to install the packages listed there.

Create files

Now that we have a virtual environment set up with some packages, we can start adding files to our project and running Python.

Let’s create a Quarto document. Open the Command Palette (Cmd/Ctrl + Shift + P) and search for and select “Quarto: New Document”. This will open a new, empty Quarto document.

Explore data

Create a new chunk with Cmd/Ctrl + Shift + I, then copy and paste in the following code to read in TidyTuesday data on weekly US gasoline prices:

import pandas as pd
import matplotlib.pyplot as plt

data_url = 'https://raw.githubusercontent.com/rfordatascience/tidytuesday/main/data/2025/2025-07-01/weekly_gas_prices.csv'
df = pd.read_csv(data_url, parse_dates=["date"])

Run the code by clicking Run cell or with Cmd/Ctrl + Shift + Enter.

Now that we’ve loaded the data, we can take a look at it in the Variables pane and Data Explorer. The Variables pane shows loaded variables.

To open the Data Explorer, click on the dataset icon next to df in the Variables pane. This opens the Data Explorer, a spreadsheet-style viewer where you can sort, filter, and preview summary statistics.

Plot

Next, let’s plot the data. Copy and paste the following code into a new cell in your Quarto document.

filtered = df[
    (df["fuel"] == "gasoline") &
    (df["formulation"] == "all")
]
filtered = filtered.sort_values("date")

for grade, group in filtered.groupby("grade"):
    plt.plot(group["date"], group["price"], label=grade)

plt.title("Gasoline prices over time")
plt.xlabel("Date")
plt.ylabel("Price (USD per gallon)")
plt.legend(title="Grade")

Run the code. Notice that the plot shows up in the plot pane on the right-hand side.

Render Quarto

Now, we can render our Quarto document. Click the Preview button in the upper-left corner of the Editor to preview your Quarto document. A rendered version will show up in Positron’s Viewer pane.

Version control

Positron makes it easy to version your work with Git. You should already have a Git repository initialized from when you created the project, but if not, you can also initialize Git within an existing folder.

You can stage, commit, and push changes to GitHub from the Source Control view in the Activity Bar:

1. Click on the Source Control view. The icon looks like this: .
2. Click the + next to each of the files you want to stage for commit. You can also click the + next to the Changes header to stage all changed files.
3. Add a commit message in the text box above the Commit button, then click Commit.
4. Click Publish Branch (the small cloud icon in the Graph section). This will create the corresponding remote on GitHub and push your changes.

Learn more about Git version control in Positron here.

Deploy

Finally, let’s deploy our Quarto document so that we can share the rendered version with others.

If you have access to Posit Connect, you can deploy directly from Positron by using Posit Publisher:

1. Click on Posit Publisher in the Activity Bar.
2. Click the + to create a new deployment.
3. Select your Quarto document.
4. Choose the deployment location. Note: if this is your first time deploying to Connect from Positron, you will need to authenticate.
5. Click the blue Deploy Your Project button.

Learn more: https://docs.posit.co/connect/user/publishing-positron-vscode/.

Wrap up

You’ve now created your first Python project in Positron. From here, you can continue developing your project and explore additional features in the IDE.

To go further:

• Explore Positron’s support for Jupyter notebooks.
• Learn how to conduct exploratory data analysis in Positron.
• Set up Positron Assistant to get AI assistance within Positron.