Python Programming with uv: All in One View

Last updated on 2025-08-13 | Edit this page

Overview

Questions

Why not use the Python included with your operating system?
Why should I use a separate installation of Python?

Objectives

Learn why you shouldn’t use the system Python.

Why not use the operating system’s Python?

Operating systems such as the various flavors of Linux include Python as part of their installation. So why not use this Python instead of installing a separate version? There are many reasons to not use the system Python:

Risk of breaking the system tools. Many operating systems use their system Python installation to run essential tools. Installing or upgrading Python packages globally can break these tools or even destabilize the operating system.
Permission issues. Modifying the system Python usually requires administrator or root privileges, which is a security risk and an inconvenience.
Version conflicts. The system Python version is often outdated and may not match the requirements of your project. Different projects may require different Python or package versions, which system Python cannot flexibly support.
Reproducibility problems. Sharing code or deploying to other machines becomes unreliable because system Python versions and installed packages can vary widely across platforms.
Lack of flexibility and control. You have little control over the version of Python installed with your operating system, and you might not be able to use newer features unless the OS itself updates to a new version.

Using a tool like uv eliminates all of these issues.

Discussion

Check your system Python

What version of Python is your operating system running? You can check this by running python --version or python3 --version in your terminal which should display the Python version. If the command is not found, then Python is not installed on your system, which is fine because we will be using uv for Python installation.

Key Points

Do not use the Python included with your operation system. Using the system Python can break system tools, cause permission errors, introduce version conflicts, limit reproducibility and flexibility with code development.
Use a tool like uv to install and manage Python instead of using the system Python. This will avoid all the issues associated with using the operating system Python.

Content from Running Python Scripts

Last updated on 2025-08-13 | Edit this page

Overview

Questions

What is a Python script?
How can I run a Python script?

Objectives

Learn about Python scripts and how to run them.
Add dependencies to a Python script.

What is a Python script?

A Python script is just a Python file like example.py. A Python file is also referred to as a module in the context of a Python package but for this lesson we will use the script definition.

Running a script with uv

Below is the contents of a Python script named example.py. This script does not have any external dependencies. It only uses features available in the Python standard library.

PYTHON

# example.py

import random


def main():
    print("Script using standard Python")
    print("Random number is", random.random())


if __name__ == "__main__":
    main()

Use the following command to run the script with uv:

BASH

uv run example.py

Running a script with dependencies

Below is the contents of another Python script named example2.py. This script imports the NumPy package which is an external dependency (not included in Python).

PYTHON

# example2.py

import numpy as np


def main():
    print("Hello from NumPy!")

    a = np.array([1, 2, 3, 4, 5])
    print("a is", a)


if __name__ == "__main__":
    main()

To run this code, uv must install the NumPy package so it can be imported by the script. The command shown below will add a script section that provides the Python version and list of dependencies.

BASH

uv add numpy --script example2.py

PYTHON

# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "numpy",
# ]
# ///

import numpy as np


def main():
    print("Hello from NumPy!")

    a = np.array([1, 2, 3, 4, 5])
    print("a is", a)


if __name__ == "__main__":
    main()

Now you can execute the script using the same run command used in the previous example:

BASH

uv run example2.py

By including the script section in a Python script, anyone can run that Python file with uv. You don’t have to worry about installing Python or creating a virtual environment and downloading dependencies. You just use uv to run the file and it will automatically install Python if it isn’t available on your computer and it will automatically install any dependencies needed to run the script.

Here is a demo of using uv to run a Python script that imports the NumPy package. This recording is animated text (not video); consequently, the text for each command is selectable and can be copied and pasted into your own terminal.

Key Points

A Python script is just a single Python file.
Dependencies can be added to a script to make it self contained.
Scripts can easily be run with uv which handles Python and installation and dependency management.

Content from Working with Python Projects

Last updated on 2025-08-13 | Edit this page

Overview

Questions

What is a Python project?
How do I create a Python project and run it?

Objectives

Create a Python project with uv.
Add dependencies to a Python project and run code.
Collaborate on a Python project with other developers.

What is a Python project?

A Python project is a directory containing multiple Python files. The metadata for the Python project is contained in a pyproject.toml file which contains information about the Python version required for the project as well as dependencies required by the project.

Create a Python Project with uv

Use the init command in uv to create a directory for a Python project. The command shown below creates a directory called my-project that represents a Python project.

BASH

uv init my-project

The contents of the directory is shown below. Notice that uv automatically sets up the directory as a Git repository and includes an ignore file to prevent unnecessary files from being committed to version control.

BASH

cd my-project

OUTPUT

my-project/
├── .git/
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

You can also use uv to add dependencies to the project. Here we add the NumPy package to the project which will automatically create a virtual environment and install the NumPy package into the virtual environment.

BASH

uv add numpy

OUTPUT

my-project/
├── .git/
├── .gitignore
├── .python-version
├── .venv/
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock

Notice that uv automatically added the NumPy package as a dependency of the project to the pyproject.toml file:

TOML

# pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "numpy>=2.3.0",
]

Lastly, to run a script in the project, just use the uv run command:

BASH

uv run main.py

OUTPUT

Hello from my-project!
a is [1 2 3 4 5]

Collaborate on Python Projects with uv

Collaborating on a Python project can be a daunting task because everyone needs to use the same version of Python and have the same dependencies (and versions of dependencies) installed in their virtual environment. However, uv makes collaboration very simple because it handles all of the installation steps for you. The basic steps for collaborating on a Python project with uv are:

Download and install uv
Download the Python project
Run the Python code in the project with uv

That’s it! There is no need to install Python on your computer, or create and activate a virtual environment, or install dependencies for running code in the Python project. This is all handled by uv when you run the code.

Key Points

A Python project is just a directory of Python files with a pyproject.toml file for configuration.
Use uv to easily add dependencies to a Python project and collaborate with other developers.

Content from Using Python Tools

Last updated on 2025-08-13 | Edit this page

Overview

Questions

What is a Python tool?
How can I install and run a Python tool?

Objectives

Install and run a Python tool with uv.

What is a Python tool?

A Python tool is just a Python package that provides a command line interface (CLI). These tools can be run directly with uv or installed globally just like any other command line application.

Run a Python Tool with uv

The pycowsay package provides a command line interface for a talking cow based on text provided by the user. The uv command shown below will run the pycowsay tool with the provided text:

BASH

uv tool run pycowsay hello there!

The output from running this command is shown below:

  ------------
< hello there! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

An equivalent command to uv tool run is uvx which is demonstrated below.

BASH

uvx pycowsay hello there!

  ------------
< hello there! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Install a Python Tool with uv

Use the uv install command to globally install a Python tool on your system. To demonstrate this, the command shown below installs the genja tool which is a static website generator built with Python.

BASH

uv tool install genja

The genja tool can now be directly run from the command line without invoking uv such as:

BASH

genja --version

This will output the following:

25.3

Use the list command to show all the tools installed by uv:

BASH

$ uv tool list

genja v25.3.1
- genja

Here is a demonstration of using uv to work with Python tools.

Key Points

A Python package with a command-line interface is a Python tool.
A Python tool can be installed, run, and managed with the uv tool subcommand.