How to open a Quarto project in GitHub Codespaces

Published

February 18, 2025

I recently received a question on YouTube about running a Quarto project in GitHub Codespaces. This was new to me, so I did some research (thanks to Mickaël Canouil and others for their help!). The key takeaway is that everything needs to be containerized: Quarto, Jupyter, the Quarto extension, R, Python, etc. Installing the VS Code Quarto extension is not enough. The easiest way to achieve this is by using the quarto-codespaces repository.

  1. Fork Mickaël’s quarto-codespaces repo: https://github.com/mcanouil/quarto-codespaces
  2. Click the green “Code” button, select “Codespaces,” and then “Create codespace on main.”

  1. Click “Authorize” and continue. Creating the codespace may take a few minutes.

  1. Once the codespace is ready, clone your Quarto project into it. For example, to clone the water-insecurity-dashboard project, run the following in the terminal:
git clone https://github.com/ivelasq/water-insecurity-dashboard.git

  1. Navigate to the project directory: cd water-insecurity-dashboard

  2. Create a new Python environment. In the Command Palette (Ctrl+Shift+P or Cmd+Shift+P), select “Python: Create Environment…”. Choose “Venv” and the appropriate Python interpreter. Very importantly, make sure you check the box to install dependencies from requirements.txt.

  1. Open your .qmd file (e.g., final.qmd) and click the “Preview” button in the top right.

That’s it! Your Quarto project should now be running in GitHub Codespaces.