02 - Getting Started with Python and uv

02 - Getting Started with Python and uv#

Lesson Overview#

The goal of this section is to gain a basic understanding of:

  1. What Python is.

  2. How to install it (we will use uv) and where it “lives” on your computer.

  3. How to run Python code.

  4. What packages are and how to install them.

  5. What virtual environments are, why they are useful, and how to create them.

We will focus on using uv to manage Python versions, create virtual environments, and install packages.

Slides#

Download the Slides

Notes#

Here is a summary of some of the most useful commands and concepts that we cover in the lecture for this section.

Terminal commands#

Here are some basic terminal commands that will help you use the command line effectively. These commands work for macOS, Linux, and the Windows PowerShell terminal (but not the windows cmd Prompt).

Tip

Reminder, To open the terminal:

  • On macOS, you can use the Command + Space shortcut to open Spotlight, then type “Terminal” and hit Enter.

  • On Windows, you can use the Windows + R shortcut to open the Run dialog, then type “powershell” and hit Enter.

Command

Description

ls

List directory contents.

cd [DIR]

Change directory to [DIR].
If [DIR] is not provided, defaults to the home directory.

pwd

Print the current working directory.

mkdir [DIR]

Create a new directory named [DIR].

Tip

When using relative paths, you can use .. to refer to the parent directory, and . to refer to the current directory.

uv cheat sheet#

uv is a fast, one-stop-shop for managing Python versions, virtual environments, and packages. It is an excellent tool to learn if you want to get started quickly with Python.

Here are some common uv commands that will help you get started using Python with uv. We will use them throughout this book.

Command

Description

uv help <COMMAND>

Useful way to get help on a specific <COMMAND>.

uv venv [ENV_PATH]

Create a virtual environment at the specified ENV_PATH.
👍 If [ENV_PATH] is not provided, defaults to .venv in the current directory.

source .venv/bin/activate
.venv\Scripts\activate

Activate the virtual environment in the path .venv

uv pip install   [PACKAGE]
uv pip uninstall [PACKAGE]

Install or uninstall PACKAGE in the current virtual environment. May use multiple packages separated by space.

uv pip list

List all installed packages in the current virtual environment.

uv run script.py

Run a Python script script.py in an on-demand virtual environment. See details below

uvx <COMMAND>
short for:
uv tool run <COMMAND>

Run a <COMMAND> provided by a Python package of the same name.
✨ This creates an environment, installs the package, and then invokes the command all in one step!

uv <COMMAND> -p <PYTHON>

Use the specified version of python (e.g. -p 3.10).
This flag works with uv tool run, and uv venv commands.

… For complete docs, see Getting started with uv.

Note

While we will not be covering it here, uv is also frequently used for project management. If you see references to commands like uv init, uv sync, uv add, or uv remove, these are only relevant in the context of using uv for project management.

uv ↔️ conda translation table#

Tip

If you are already familiar with conda, here is a quick translation table to help you understand how uv commands map to conda commands:

uv command

conda equivalent

Description

uv venv

conda create

Create a new env

source .venv/bin/activate
.venv\Scripts\activate

conda activate

Activate the virtual environment in the path .venv

uv pip install

conda install

Install a package into the env

uv pip uninstall

conda remove

Remove a package from the env

uv pip list

conda list

List all packages in the env

uv run#

uv run is a command that allows you to run a command or script in an on-demand virtual environment.

If you have a simple python script named hello.py, that has no dependencies:

print("Hello, world!")

You can run it with:

uv run hello.py

… which is shorthand for uv run python hello.py.

… For complete docs, see Running scripts.

uv run with additional dependencies#

A particulary useful feature of uv run is that you can specify dependencies in your script using a special syntax in a comment at the top of the file.

For example, the following example_script.py uses two packages, requests and rich, to download and print a JSON file downloaded from the internet in a nice format:

# /// script
# dependencies = ["requests<3", "rich"]
# ///

import requests
from rich import print

resp = requests.get("https://jsonplaceholder.typicode.com/posts")
print(resp.json())

With uv you can run this script without having to first create an environment and install the necessary dependencies, simply by running:

uv run example_script.py

… For complete docs, see Declaring script dependencies.

Running Jupyter notebooks with juv#

💡 Think of juv as uv run for Jupyter notebooks.

juv is a command line tool built on top of uv that provides a convenient way to run a Jupyter notebook, with all the necessary dependencies, in an on-demand virtual environment.

It is built on the following concepts:

  1. As we saw above: uvx juv is shorthand for “run the command juv from the package juv.

  2. As we saw above: uv can read dependencies specified inside of a script.

  3. juv just brings along the necessary Jupyter notebook dependencies and parses the dependencies from the top of your notebook for uv.

Command

Description

uvx juv init <name.ipynb>

Initialize a new Jupyter notebook named <name.ipynb>.

uvx juv add <name.ipynb> <PACKAGE>

Add a new dependency to the comment at the top of <name.ipynb>.

uvx juv run <name.ipynb>

Launch a Jupyter notebook server and run the notebook <name.ipynb>.

… For complete docs, see the juv repository.

Contents