Install an IDE and uv for Python package management

Environment Setup

Integrated Development Environment (IDE)

We will use VS Code.

Download the installer for you platform. After installation do the following:

• Add the following extensions (Ctrl + Shift + x):
  • Git Graph (mhutchie)
  • Jupyter (Microsoft)
  • Python (Microsoft)
  • Code Spell Checker (Street Side Software)

Build Tools

Some packages we want to use are not prebuilt, thus we need some build tools.

• For Windows users
  • Get the installer: https://visualstudio.microsoft.com/de/visual-cpp-build-tools/
  • Install the Microsoft C++ build tools
• For Ubuntu users
  • Run the following to install build tools

  sudo apt update
  sudo apt install build-essential

• For MacOS users
  • Run the following to install build tools

  xcode-select --install

uv

Installation

• For Windows users
  • Open Windows PowerShell and do:

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• For Ubuntu and MacOS users
  • Open a terminal and do:

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

Open VS Code -> open a new terminal (Ctrl + shift + ö) -> run uv --help the output should look like this:

An extremely fast Python package manager.

Usage: uv [OPTIONS] <COMMAND>

Commands:
  run      Run a command or script
  init     Create a new project
  add      Add dependencies to the project
  remove   Remove dependencies from the project
  sync     Update the project's environment
  lock     Update the project's lockfile
  export   Export the project's lockfile to an alternate format
  tree     Display the project's dependency tree
  tool     Run and install commands provided by Python packages
  python   Manage Python versions and installations
  pip      Manage Python packages with a pip-compatible interface
  venv     Create a virtual environment
  build    Build Python packages into source distributions and wheels
  publish  Upload distributions to an index
  cache    Manage uv's cache
  self     Manage the uv executable
  version  Display uv's version
  help     Display documentation for a command

Cache options:
  -n, --no-cache               Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation [env: UV_NO_CACHE=]
      --cache-dir <CACHE_DIR>  Path to the cache directory [env: UV_CACHE_DIR=]

Python options:
      --python-preference <PYTHON_PREFERENCE>  Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=] [possible values: only-managed, managed, system, only-system]
      --no-python-downloads                    Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]

Global options:
  -q, --quiet                                      Do not print any output
  -v, --verbose...                                 Use verbose output
      --color <COLOR_CHOICE>                       Control colors in output [default: auto] [possible values: auto, always, never]
      --native-tls                                 Whether to load TLS certificates from the platform's native certificate store [env: UV_NATIVE_TLS=]
      --offline                                    Disable network access [env: UV_OFFLINE=]
      --allow-insecure-host <ALLOW_INSECURE_HOST>  Allow insecure connections to a host [env: UV_INSECURE_HOST=]
      --no-progress                                Hide all progress outputs [env: UV_NO_PROGRESS=]
      --directory <DIRECTORY>                      Change to the given directory prior to running the command
      --project <PROJECT>                          Run the command within the given project directory
      --config-file <CONFIG_FILE>                  The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=]
      --no-config                                  Avoid discovering configuration files (`pyproject.toml`, `uv.toml`) [env: UV_NO_CONFIG=]
  -h, --help                                       Display the concise help for this command
  -V, --version                                    Display the uv version

Use `uv help` for more details.

If you want, you can now dive into Python package management by reading the uv documentation.

Python and python package management with uv

Build your own environment

The goal is to create a Python environment and define packages from scratch.

init uv project

Open a terminal e.g. via VS-Code --> Terminal --> new Terminal. The terminal will prompt you the current path where you are e.g.:

# for power shell windows:
PS C:\projects\

C:\projects\ is just an example that exist on my machine, your path can look different.

Excursus: Shell commands

Command	Description	Example
pwd	Print working directory - shows the current directory.	pwd
ls	List directory contents - shows files and directories in the current directory.	ls, ls -l, ls -a
cd	Change directory - navigates to a specified directory.	cd Documents, cd ..
mkdir	Make directory - creates a new directory.	mkdir NewFolder
rm -r	Remove recursively - deletes a directory and its contents.	rm -r FolderToDelete
rm	Remove file - deletes a file.	rm file.txt
cp	Copy file or directory.	cp file.txt new_file.txt
mv	Move or rename file or directory.	mv file.txt new_location/file.txt

You will now initialize a uv managed workspace named uv-demo with a Python 3.12 definition. Workspace is a fancy name for directory with a specific content:

# Navigate to a folder you want to create the demo folder in.
# The next line will create a new folder called uv-demo at your current location
uv init -p 3.12 uv-demo
>>> Initialized project `uv-demo` at `C:\projects\uv-demo`
# after initialization change into the new folder
cd uv-demo
# look around, this is what you will see
ls
# ls -la for Mac or Unix
>>>     Directory: C:\projects\uv-demo


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----          4/7/2025   3:37 PM              5 .python-version
-a----          4/7/2025   3:37 PM             85 main.py
-a----          4/7/2025   3:37 PM            153 pyproject.toml
-a----          4/7/2025   3:37 PM              0 README.md

The current location C:\projects\uv-demo is called the root of our uv managed project!

The most important file you have created is the pyproject.toml. If you want to keep it clean, you can simply remove all other files, but keeping them is no problem too.

# check what is in pyproject.toml
cat pyproject.toml
>>> [project]
name = "uv-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

We see that currently, only Python is defined to be version 3.12 or later, but no packages.

Add packages to uv project

In this mini example, we want to load tabular data, thus we install pandas a popular Python package for tabular data. We also want to run interactive jupyter notebooks, thus we have to install the interactive python kernel which we get via jupyterlab.

# Do this inside the root of the uv project we have initialized.
# On my machine: C:\projects\uv-demo
uv add pandas jupyterlab

# check what has happened:
cat pyproject.toml
>>> [project]
name = "uv-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "jupyterlab>=4.4.0",
    "pandas>=2.2.3",
]

uv has automatically downloaded the packages and all dependencies, and registered the two added packages as major dependencies in the dependencies list inside the pyproject.toml.

Use the workspace and the environment

Workspace

Inside a new VS-Code Window, go to the file browser menu (left hand side) Ctrl+Shift+E and click the button Open Folder. Navigate to the folder you have created with uv e.g. uv-demo and select this folder.

NOTE: Do not go into the folder and select the .venv directory inside! Only select the root of our uv managed project.

VS-Code will load your workspace and you can now brows all the files in uv-demo inside VS-Code. e.g. open the pyproject.toml file if you like.

• create a new folder in the root called data.
• Add the data.parquet file from this gist to data.
• create a new folder in the root called notebook
• inside notebook create a test.ipynb file.

Now, your workspace should look like this:

.venv or kernel

The file test.ipynb is an interactive python notebook. When you open this file, there is a symbol, Select Kernel, in the upper right corner. Some VS-Code-Operating System combinations run an autodetect for kernels, thus it is possible that you already see a selected python version or a working kernel detection. In either way, click on the Select Kernel or version name of the auto detected Python kernel. In the pop up menu, select Python Environments which will lead you to a similar overview like this:

Here you are always interested in the project's virtual environment .venv (setup by uv). In the screenshot you see that the recommended environment is the project's environment, with a relative path, to the root of the workspace. All other environments have absolute paths (starting with c:\ or ~) which is a sign for you that this is not what you want to select.

TROUBLESHOOTING: When this menu, after several retries never shows you the relative .venv environment and you are sure, that the .venv has been correctly created in your workspace (check the file browser in VS-Code), then it is likely that one of your extensions is not working properly. In VS-Code go to Extensions tab. Uninstall the Python and Jupyter extensions. Restart VS-Code, install the Python and Jupyter extension. And try again.

Check if your setup works

After the kernel is connected to your notebook, you can see the python version and .venv reference in the upper right corner. Now click + Code to write a Python code cell in your notebook. And add:

import pandas as pd

Run this cell with e.g. Shift+Enter, this will automatically insert a fresh cell below and execute the current cell.

In the new cell, try to use pandas to read in the data.parquet table:

data = pd.read_parquet('../data/data.parquet')
data.head()

When you execute this block, the cell will fail. Check the error message:

ImportError: Unable to find a usable engine; tried using: 'pyarrow', 'fastparquet'.
A suitable version of pyarrow or fastparquet is required for parquet support.
Trying to import the above resulted in these errors:
 - Missing optional dependency 'pyarrow'. pyarrow is required for parquet support. Use pip or conda to install pyarrow.
 - Missing optional dependency 'fastparquet'. fastparquet is required for parquet support. Use pip or conda to install fastparquet.

Use pip or conda to install pyarrow

This is important, the error tells us what to do! We have to install a package, and we will do this with uv since we do not want any other package installation program to interfere with our uv managed environment. Only by using uv to handle all packages in our project, this setup is consistent and stable! But, luckily it is super easy:

uv add pyarrow

Now, restart the kernel (upper center in your notebook tab, looks like a refresh button), and run all cells again:

And, for the record, check your pyproject.toml:

cat pyproject.toml
>>> [project]
name = "uv-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "jupyterlab>=4.4.0",
    "pandas>=2.2.3",
    "pyarrow>=19.0.1",
]

Exercise

Try 3 uv environments in 30 Minutes

The idea is to get used to see processing environments as ephemeral structures. If a random person provides you a laptop or a supercomputer, you have to be able to perform your skills on both without a huge effort to set them up. Or another example, you shouldn't be bothered if your laptop breaks down today, because you know you can pop up your processing environments anywhere in no time, and of course you have a solid backup strategy for your other data like code etc. ... right?

For each of the following environments

• start from scratch by using uv init to setup a fresh workspace
• use uv add to add the mentioned packages
• create a test.ipynb notebook, connect to the fresh .venv and run the example code.

The tabular environment

packages:

• jupyterlab
• pandas
• matplotlib

run this code:

import pandas as pd
import matplotlib.pyplot as plt

# Create some tabular data
data = pd.DataFrame({
    'Category': ['A', 'B', 'C', 'D', 'E'],
    'Values': [23, 45, 56, 78, 89]
})

# plot the data
plt.figure(figsize=(8, 6))
plt.bar(data['Category'], data['Values'], color='skyblue')
plt.xlabel('Category')
plt.ylabel('Values')
plt.title('Simple Bar Plot')
plt.grid(axis='y', alpha=0.75)
plt.show()

The spatial environment

packages:

• jupyterlab
• geopandas
• geodatasets
• matplotlib

import geopandas as gpd
import matplotlib.pyplot as plt
from geodatasets import get_path

# Get the data
nybb = gpd.read_file(get_path('nybb'))

# Plot it
fig, ax = plt.subplots(figsize=(12, 8))
nybb.plot(ax=ax, color='lightgrey', edgecolor='black')

# Add title
plt.title('New York boroughs')

# Remove axis
ax.set_axis_off()

plt.tight_layout()
plt.show()

The visual environment

packages:

• jupyterlab
• plotly
• numpy

import plotly.graph_objects as go
import numpy as np

# Create 3D data
n_points = 1000
x = np.random.randn(n_points)
y = np.random.randn(n_points)
z = np.random.randn(n_points)

# Create a color gradient based on z
colors = z

# Create the 3D scatter plot
fig = go.Figure(data=[go.Scatter3d(
    x=x, 
    y=y, 
    z=z,
    mode='markers',
    marker=dict(
        size=5,
        color=colors,
        colorscale='Viridis',
        opacity=0.8,
        colorbar=dict(title="Z Value"),
    )
)])

# improve layout
fig.update_layout(
    title="3D Rotating Point Cloud",
    scene=dict(
        xaxis_title='X Axis',
        yaxis_title='Y Axis',
        zaxis_title='Z Axis',
        aspectmode='cube',
        camera=dict(
            eye=dict(x=1.5, y=1.5, z=1.5)
        )
    ),
    width=800,
    height=800,
)

fig.show()

Delete all created workspace directories with all files, because it was not really a thing to create them and you know that you can do it in probably 5 minutes for each of them next time you need them - let go.