MacOS Python setup

$ MacOS Python setup.md

Python project setup on MacOS

Here are two ways to set up a Mac for Python projects, assuming VSCode is already installed. The "new way" is much easier, but you may not have access to uv for some reason, so the "old way" is also shown.

The new way

Install uv.

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a folder, open it in VSCode, and initialize the folder. This will create a pyproject.toml to track our dependencies, but uv will take care of all the details.

uv init --bare

Synchronize the local virtual environment.

If this results in a virtual environment being created for the first time, confirming the "would you like to select it for your workspace" prompt will automatically do this for you in all future shell sessions in VSCode.

uv sync

Add the packages you wish to install using uv. It will update the pyproject.toml, keeping track of the lower bound of compatible package versions.

uv add ipykernel matplotlib notebook numpy pandas pillow scipy

Note that it is not necessary to activate the virtual environment. You can always ensure you're running something from the local virtual environment by invoking it like uv run .... Here are some examples.

# All of these correctly use the virtual environment without it having to be activated.
# Launch a Python interpreter
uv run python
# Launch a Python module (`this` is an Easter Egg that recites the Zen of Python)
uv run -m this
uv run --module this
# Run a Python script
uv run --script script.py

That's it! You should be able to create and run Python scripts (e.g. script.py) and Jupyter notebooks (e.g. notebook.ipynb) now.

The old way

Install Homebrew.

curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh

Install Python. You may need to log out and back in or reboot for brew to work at command line. brew will launch the binary at /usr/local/bin/brew or /opt/homebrew/bin/brew

brew install python

Create a folder, open it in VSCode, and create a virtual environment. Click to confirm if prompted "We noticed a new virtual environment has been created in your workspace. Would you like to select it for your workspace?" Confirming this prompt will automatically do this for you in all future shell sessions in VSCode.

python3 usually points to the latest Python on your machine. You can specify the exact Python version like python3.11 or python3.12 instead if you like. Note that python alone will probably not point to a Python version on MacOS.

python3 -m venv .venv

To activate the virtual environment manually, do the following. VSCode does this automatically if you confirmed the prompt mentioned in the last step.

source .venv/bin/activate

Create a requirements.txt and type packages in it as follows (ipykernel and notebook will be needed for some Jupyter notebook functionality in VSCode).

ipykernel
matplotlib
notebook
numpy
pandas
pillow
scipy

Install these packages in to the virtual environment.

pip install --requirement requirements.txt