Welcome

Our goal is pyenv, python, poetry, vscode and quarto working seamlessly with python virtual environments from a command line.

Getting your machine ready for software development can sometime be challenging, especially if over time you’ve accumulated lots of software on your computer.

This site offers a process for preparing your computer for python development using VS code and Quarto from the command line. Those on Mac (zsh shell) and Linux (bash shell) have an easier time. Those on Windows have a tougher time because of the multitude of shells (e.g., CMD, powershell-5 or powershell-core).

Getting started

  1. Visit terminals to learn about command line terminals,
  2. Visit prework to make some adjustments before you install the tools,
  3. Visit software to find instructions and checklists for installing software in the correct order,
  4. Visit final steps to verify that all is working well,
  5. Visit vscode to properly configure VS Code.
  6. Visit utils for a few useful command line commands and utilities.

These are all menu options at the top of the page from left-to-right.

Already started, or having problems?

Visit troubleshooting or checklist below.

How do you know your tools are working together?

If your install is good, you should be able to:

  • switch pythons using pyenv.
  • verify that the command quarto check uses the appropriate pyenv python.
  • create a virtual environment using poetry init.
  • verify that the command poetry shell works with the correct shell.
  • while poetry shelled into a venv, verify that quarto check is using python from the venv.
  • while in VSCODE, verify that ctrl-shift-k renders a document using the correct venv.
  • while in VSCODE, verify that the terminal opens the correct shell and uses the correct venv.

About this site

Each section on the site offers guidance on individual installation and configuration steps. The final steps section offers guidance on getting them all work together.

Source code for the site is available on GITHUB. Please improve the site!

Glossary of terms

To eliminate confusion I’ll be using the following terms on this site:

VSC
visual studio code. An awesome code editor and more. See IDE below.
terminal
A command line windows NOT inside VSC. On windows we’ll use a terminal window with powershell. On mac you’ll use terminal window with ZSH. On linux you’ll use a terminal windows with bash.
GUI
a graphic user interface, often directly associated with the underlying operating system.
IDE
an integrated development environment. While very handy when learning to code, they quickly become a crutch for software engineers and coders. PyCharm is one example of an IDE.

In closing, VSC is NOT an IDE although many people use it like an IDE. VSC includes many features of an IDE and is very extensible. However, VSC can also be used as a regular code editor, like VIM, EMACS or others. Learn to use VSC from the command line!

Troubleshooting

For the most part everyone has their tools already installed and the challenge is getting them to all work together. Here are some tips:

  • Be patient and methodical. Debugging can be frustrating. YOU GOT THIS!
  • Get everything running outside of VSC before you try running inside VSC. (See terminal)
  • Verify that you did ALL the required install steps. I’ve seen people not read the instructions completely and are left with half-working software. This is VERY hard to debug!
  • Verify that the individual tools are working by themselves.
  • Use quarto check to see how things are working together.
  • Once everything runs from a terminal then jump inside VSC to get it all running there.
  • If you still have trouble, consider uninstalling/remove the tools and starting over.

Many of the problems that I’ve seen result from not completing the install. For most software engineering tools, simply installing the software is only the first part.

Many software tools require second or third steps that make the use of the installed software easier from the command line. RTFM

Checklist

If your system is not working or if you’re starting from scratch, here is a general checklist:

If the tools are completely installed in the correct order, everything should work out of the box in mac and linux. The PC will require a few more tweaks. (See final steps)

What do I do now?

I’m here because my system isn’t working. How do I get started? What do I do now? Start with the Checklist!