A step-by-step guide to setting up VS Code for local Python development (primarily macOS) with pyenv and Pipenv.

README.md

Setup a Python dev environment using pyenv and Pipenv with VS Code

This setup will enable the use of a virtual environment with VS Code with the Python and Jupyter Notebook VS Code Extensions. It ensures that the instance of Python is isolated and that any packages that get installed via Pipenv are also isolated to this project.

NOTE: This guide is generally for setup on macOS but should be similar for Windows and Linux users.

VS Code Packages for Python Development

To use Python with VS Code, the following packages should be installed. A more comprehensive set of packages and settings can be installed via this Data Engineering profile (instructions included).

Jupyter 🪐

Provides basic notebook support for language kernels that are supported in Jupyter Notebooks today, and allows any Python environment to be used as a Jupyter kernel. This extension bundle includes the following supporting extensions: - Jupyter Keymap - to provide Jupyter-consistent keymaps - Jupyter Notebook Renderers - to provide renderers for MIME types such as latex, plotly, vega, etc. - Jupyter Cell Tags and Jupyter Slide Show - to provide the ability to tag cells in notebooks and support for presentations

Python 🐍

Rich support for the Python language (for all actively supported versions of the language: >=3.7), including features such as IntelliSense (Pylance), linting, debugging, code navigation, code formatting, refactoring, variable explorer, test explorer, and more. Includes supporting Pylance extension: - Pylance

File Nesting Updater [optional] 🗂️

While not a requirement, if installed, this setup will take advantage of the File Nesting Updater extension. This helps keep your workspace tidy despite the various dotfiles and configuration settings you have specified.

Jupyter notebook settings

The interactive window will open to the right of the active code editor and 'perFile' will create a new interactive window for every file that runs a cell. Other options include:

• viewColumn = 'active' will open the interactive window in place of the active editor.
• viewColumn = 'secondGroup' will open the interactive window in the second editor group.
• creationMode = 'single' allows a single window.
• creationMode = 'multiple' allows the creation of multiple.

Tip

The executeSelection=true allows you to highlight Python code and run it in an interactive window by pressing shift + enter.

    "jupyter.interactiveWindow.creationMode": "perFile",
    "jupyter.interactiveWindow.textEditor.executeSelection": true,
    "jupyter.interactiveWindow.viewColumn": "beside",

Prerequisites

For this setup, we will need to have pyenv and pyenv-virtualenv as well as pipenv installed. These can be installed with Homebrew on MacOs (recommended). Instructions for alternate installation and on Windows can be found with their documentation.

Pyenv : https://github.com/pyenv/pyenv

Pipenv : https://realpython.com/pipenv-guide/

NOTE: While it is recommended that Pipenv should be installed with pip, Homebrew is a simpler option (IMHO) and keeps it with other Homebrew installs. I recommend Homebrew if that is an option. However, you can use pip/pip3 if you prefer.

Homebrew Install

brew install pyenv

brew install pyenv-virtualenv

brew install pipenv

1. Create a VS Code Workspace

• Choose File → Save Workspace As...
• Name your workspace (e.g. python-experiments)

1.a Install a viable Python version (if needed)

You might not want/need the latest version of Python. For example, I recently needed to use the faiss-cpu package. Python 3.12 and above is currently incompatible with the faiss-cpu package. Until this gets resolved, I needed to use the latest version of Python 3.11 → e.g. 3.11.7. To do so I used 'pyenv: Install Python → pyenv install 3.11.7 to install a recent but compatible version.

2. Create a local virtual environment container

When we create this container, we'll point it to the instance of Python installed with Pipenv (or use one that was previously installed). It is standard practice to name the container .venv (or venv) and we'll do this to take advantage of the File Nesting Updater extension.

NOTE: While both pyenv and Pipenv can be used by themselves to create and use a virtual Python environment, in order to use VS Code for Python development, it will need a Python kernel and the ipykernel package to run code in an interactive console and inside Jupyter notebooks. By creating a local virtual environment container, VS Code will automatically detect and use the one created without prompting us to install ipykernel.

• Create the virtual environment e.g. pyenv virtualenv 3.11.7 python-experiments

This command instructs pyenv to use virtualenv to create a virtual environment with the version specified and the name that is given. This helps keep track of what environments get created, so a descriptive name is recommended.

• Set the local environment to use the newly created virtual enviroment e.g. pyenv local python-experiments

This will create a .python-version dotfile with the virtual environment name that was specified.

• Create the .venv container e.g. python3.11 -m venv .venv
• Initialize the Pipfile for Pipenv → pipenv shell

This will detect the virtual environment and use it instead of creating one and will also detect if a requirements.txt file is present and add the contents to the Pipfile.

• Add the ipykernel package to the Pipfile under the [dev-packages] section with the value of ipykernel = "*" and save it

Commands to create the virtual environment

pyenv virtualenv 3.11.7 python-experiments # Use whatever version and name makes sense here
pyenv local python-experiments # The name used in the previous step will tell `Pipenv` which virtual environment to load
python3.11 -m venv .venv # The VS Code File Nesting feature will come in handy here 
pipenv shell

As noted above, ipykernel is required by VS Code to run Python in an interactive console and inside Jupyter notebooks. This can also be done by installing and saving it to dev with the command pipenv install ipykernal --dev

Pipfile with ipykernel

3. Install package dependecies with Pipenv

The Pipfile will be used to install any packages that are missing and create a lockfile. The packages will be installed in the local .venv container in the lib subfolder.

• Install the packages pipenv install --dev

Command to install packages with Pipenv

pipenv install --dev

4. Verify the installation

Once the install completes without errors, open or create a Python file and run some Python code in an interactive window.

• Add these lines of Python to the .py file e.g. scratch.py

import sys
print("Python version:", sys.version)
print("Python location:", sys.executable)

• Highlight the lines in the file and press shift → enter

The version should match what was specified when creating the virtual environment and the location should be under .venv/bin/python in the project workspace.