Quarto, Python, and VS Code: Quarto Reports In VS Code


Quarto, the successor of R Markdown, is a powerful tool for creating reports and presentations. In this blog post, I’ll show you how easy it is to use Quarto in Visual Studio Code (VS Code) together with Python. Make your coding experience a breeze and learn useful techniques with Quarto.

In an earlier post, we discussed what quarto is capable of when it comes to working with R in RStudio. But that’s only one part of the data science and machine learning world. The other big player – is Python.

Need help with Posit (RStudio) data science products for your project? Appsilon can help with end-to-end service as a Full Certified Partner and product reseller.

And as Posit (formerly RStudio) pushes forward with more language agnostics products, it’s never been a better time to learn how their data science products can interact with other tools.

Table of contents:


Quarto support in VS Code

First, you’ll need to install the tool. You can do that by following the steps for installing in our R Quarto tutorialSecond, you’ll need to install the Quarto extension for VS Code. This can be done by following the official Quarto tutorial.

Now everything is set up and ready for experimenting and reporting!

Next, let’s explain the ‘why’ before you invest any more time. 

Why would I bother with Quarto in VS Code?

It’s fair to say that RStudio is the go-to, gold standard IDE for R programmers. However, that’s not the case with Python. Most data scientists favoring Python tend to use other options like VS Code. 

FYI – are you using RStudio Workbench? Explore Posit’s (RStudio) solutions for developing Python with RStudio IDE, VS Code, Jupyter Notebook, and more. 

For those of you entrenched in your preferred editors, it might be easier to use Quarto in VS Code than in RStudio IDE. You can keep all of your favorite colors’ themes, configurations, and shortcuts across programming in different languages to make life simpler.

Of course, Quarto in VS Code is still Quarto, so the overall capabilities are the same. There is nothing wrong with running Python in RStudio. Even more so, we encourage you to experiment with it if you have experience in using RStudio. This can also be particularly helpful if you work with distributed teams and need a one-stop shop for distributed teams like Posit (RStudio) Connect.

Python basics in Quarto and VS Code

Working with Quarto files live in VS Code

To begin, .qmd files can be used the same way as the .py files with ##% in VS Code when it comes to running them line-by-line. The only difference is that you write code in chunks like:

qmd file python debug quarto

instead of:

.py file python debug quarto

The VS Code magic trick to pick any python from the installed environments as an interpreter for the current file works wonders. Other tricks like running cells out of order, although not recommended, also work without any problems.

New to Python and prefer working in R? Learn how to use R and Python together!

What positively surprised me was the out-of-the-box support of shortcuts like ctrl+shift+I for chunk creation that I was used to from RStudio. The autosuggestions for Quarto parameters were also genuinely useful!

Quarto run cell shortcuts

Rendering Python qmd files with Quarto

You’ll rarely use Quarto just to run lines out of order. It’s all about creating beautiful, interactive reports!

First, you must specify the Jupyter kernel that should run the code in the document yaml. For example, to choose the “chosen-kernel-name” kernel, you should write:

title:"Example qmd file"
jupyter:"chosen-kernal-name"

This means that you must register your Python/Conda environment to jupyter before you render the document. Then it’s as easy as running Quarto: Render command from VS Code ctrl+shift+P panel!

quarto render command from vs code ctrl+shift+p

Using the latest versions of Quarto (1.0.35) and Quarto VS Code Extension (1.28.0) I wasn’t able to render .ipynb files this way and I had to rely on the CLI version of Quarto. This will likely be addressed in upcoming versions.

Some might remember that the R Markdown format had an issue with forgetting the Python variables between code chunks so each chunk had to be a separate program, so to say. That’s no longer a problem using Quarto!

Example of Quarto report with Python

Quarto demo

Quarto VSCode demo

Let’s briefly explore a few distilled features of Quarto. Isn’t all this interactivity and linkability amazing? The code you want to show is visible but imports are not. The auto-generated table of contents is also here!

The above demo has been rendered using the following code:

---
title: "Quarto report"
jupyter: "python310-ds"
format:
  html:
    theme:
          light: flatly
          dark: darkly
    toc: true
---

My first Python in Quarto report!

## Data loading

Table @tbl-iris presents data on the Iris dataset.

```{python}
#| echo: false
import pandas as pd
import matplotlib.pyplot as plt
```


```{python}
#| code-fold: true
#| tbl-cap: The Iris dataset
#| label: tbl-iris
df = pd.read_csv("data/iris.csv")
df
```

## Plots 

```{python}
#| label: fig-variety-histogram
#| fig-cap: Histogram of sepal lengths
#| fig-align: center
#| code-fold: true
df.groupby("variety")["sepal.length"].hist(alpha=0.5, legend=True)
plt.show()
```

Cool! We've created @fig-variety-histogram to learn more about iris sepal lengths distribution, using data from @tbl-iris.

As you can see, everything is quite simple and uses the exact same Quarto syntax as the reports in R.

Suggested workflow for Quarto in VS Code

The feature of re-rerendering the report every time you save is impressive, handy, and often desired by users. But this isn’t always the case. For example, if you work with large reports that involve heavy computation, it might actually be suboptimal. 

You might try using Quarto cache. Unfortunately, at the time of writing this post, this feature is not fully supported. In such a case, you can try using Jupyter notebooks instead of qmd files (they work with Quarto as well!) or work in an interactive way within VS Code and render the report presentation after some time.

Closing notes on Quarto with Python in VS Code

Even without using the intricate features of Quarto, the reports generated using it are just beautiful. But those additional features are available, and you can absolutely make your reports top of the line! 

Everything can be interactive with plotly plots embedded. From the moment I discovered Quarto, I’ve begun using it every time I have to present some insights from data! Although I have to say, I prefer to use Quarto with Jupyter notebooks instead of qmd files. But don’t worry they will be covered in the next post!

Py/Shiny (Shiny for Python) is still in beta. Until then, check out Python Dash vs R Shiny to compare dashboards for your project reporting.

Not all of the features are fully supported yet. But I’m sure they’ll begin rolling out after the official release of Quarto. So I’ll be keeping my eyes peeled for updates on RStudio’s blog!

Environment

This post was written under:

  • Quarto quarto-1.0.35-linux-amd64
  • Quarto VS Code extension v1.28.0

Quarto is a quickly developing software, you may not encounter some problems that I did! Or you may encounter other issues. Let us know in the comments below, if you ran into anything puzzling and how you resolved it.