2 Python Management

Python continuously releases new versions. Similarly, individual Python packages (hosted on PyPI) also continuously release new versions. Python scripts usually have dependencies on specific Python versions and packages, which highlights the need to carefully managing these. This is similar to different versions of MIKE+: you would not expect a MIKE+ 2025 model to run with MIKE+ 2023.

2.1 Tools

There are several tools for managing Python and packages together. Two common options are:

uv
Miniforge

This course uses uv. Please install uv according to their official installation instructions. Use the “standalone installer” for Windows.

Confirm you properly installed uv by opening a terminal and running:

uv --version

Learn basics of terminals

Installing and using uv requires using a terminal. Being familiar with terminals is generally useful for Python. This course assumes basic knowledge. If you’ve never used a terminal before, then please refer to an introductory resource such as: Windows PowerShell.

2.2 Installing Python with uv

You can install Python with uv from the command line:

uv python install

By default, this installs the latest version of Python (3.13.2 at the time of writing).

Confirm it installed correctly by running:

uv run python --version

2.3 Virtual Environments

Note

Virtual environments are an advanced Python topic, however, they are fundamental to using uv. Therefore, they will not be covered in depth, but explained just enough to be useful.

Virtual environments are useful for isolating dependencies between projects. For example, let’s say you work on two projects: Project A and Project B. If Project A requires a different version of Python than Project B, then you can handle that by creating virtual environments for each project. This avoids a common issue encountered when not using virtual environments. Conceptually, a virtual environment is a single Python version and set of Python packages.

Create a new folder, and make a virtual environment:

uv venv

Tip

Use the terminal cd command to change its current directory. Alternatively, install Windows Terminal to easily launch a terminal from a folder within File Explorer via the right-click context menu.

Notice a folder called .venv was created. Explore that folder to see what it contains. Can you find the file Python.exeand the folder site-packages?

It’s good practice to create a single virtual environment in the root directory of each project. Therefore, the remainder of this course assumes you always run uv from within a folder containing a virtual environment.

Refer to uv’s documentation for additional details.

2.4 Python package management

uv provides two different approaches for Python package management. This course uses their pip interface. Common workflows are shown in the following sections. Refer to uv’s documentation for more details.

2.4.1 Install packages

Install Python packages with uv as follows:

uv pip install <package-name>

For example, install mikeio as follows:

uv pip install mikeio

Look at the site-packages folder again. Notice that it now includes mikeio and many other packages. When a package is installed, all of its dependencies are also installed automatically.

2.4.2 List installed packages

List all installed Python packages and their versions with:

uv pip list

2.4.3 Upgrade packages

Upgrade an older package version to the latest version as follows:

uv pip install --upgrade mikeio

2.4.4 Install specific package versions

Occasionally there’s a need to install an older version of a package, which can be done as follows:

uv pip install mikeio==1.7.1