Python Programming with uv: All in One View

Last updated on 2025-08-14 | 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 operating system. Using the system Python can break system tools, cause permission errors, introduce version conflicts, as well as 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 Anaconda and Pixi

Last updated on 2025-09-02 | Edit this page

Overview

Questions

What is Anaconda?
What is pixi?

Objectives

Recognize the use cases for Python programming with Anaconda.
When to use Pixi for Python projects.

What is Anaconda?

Anaconda is a popular package and dependency management platform used primarily for Python programming in data science and scientific computing. It is bundled with a wide range of pre-built packages and includes the Conda package manager. Anaconda/Conda offer package management support for C and C++ libraries and other programming languages but it is mostly used for Python.

It should be noted that Anaconda’s license agreement requires organizations of more than 200 employees to purchase a business license. This may be cost prohibitive for some companies and institutions. Contrast this with uv which does not have such license restrictions.

What is Pixi?

Pixi is a package manager that supports multiple programming languages including Python; although, its Python support is provided through uv. Pixi is a good alternative to Anaconda if you need to use libraries or packages that are only available through Conda.

Key Points

Anaconda offers easy installation and package management for multi-language projects but its license restrictions can be cost prohibitive.
Pixi is a good alternative to Anaconda/Conda but it still relies on uv for Python package management.
For Python projects, uv offers better dependency management and faster installation compared to Anaconda/Conda and Pixi.

Content from Running Python Scripts

Last updated on 2025-08-20 | 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 refer to a Python file as a script.

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

OUTPUT

Script using standard Python
Random number is 0.8227936022620481

Without uv, you would typically run this Python script using the $ python example.py command in the terminal.

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 the Python standard library).

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

This is the script section that was added at the top of the Python file:

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

OUTPUT

Hello from NumPy!
a is [1 2 3 4 5]

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.

Below 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 in the demo 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 installation and dependency management.

Content from Working with Python Projects

Last updated on 2025-08-20 | 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 are shown below. Notice that uv automatically sets up the directory as a Git repository (.git/) and includes an ignore file (.gitignore) to prevent unnecessary files from being committed to version control. The .python-version file contains the project’s default Python version.

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 (.venv/) and install the NumPy package into the virtual environment. A uv.lock file is also created to ensure that developers working on the project are using a consistent set of package versions.

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 such as main.py in the project, just use the uv run command as shown below:

PYTHON

# main.py

import numpy as np


def main():
    print("Hello from my-project!")

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


if __name__ == "__main__":
    main()

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. For projects that contain a pyproject.toml file, 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 the uv run command

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.

For projects that don’t provide a pyproject.toml file, you may need to manually create the virtual environment with uv then install dependencies with pip as summarized below. Unfortunately, there are many ways to setup a Python project, so the steps needed to install and run such a project may vary if there is no pyproject.toml file.

Download and install uv
Download the Python project
Create the virtual environment for a specific Python version with uv venv --python 3.12
Install dependencies in the environment with the uv pip install command
Activate the virtual environment and run code with the python command

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-09-02 | Edit this page

Overview

Questions

What is a Python tool?
How can I install, run, and manage 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 package with the provided text. Notice there is no need to install Python, create a virtual environment, activate the virtual environment, and install the pycowsay package into the environment. You just use uv to directly run the pycowsay package; uv will handle installation and virtual environment creation automatically.

BASH

$ uv tool run pycowsay hello there!

OUTPUT

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

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

BASH

$ uvx pycowsay hello there!

OUTPUT

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

Here is a demo of using uvx to run the pycowsay tool:

Install, upgrade, and remove a Python tool

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 run directly from the command line without invoking uv such as:

BASH

$ genja --version

OUTPUT

25.3

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

BASH

$ uv tool list

OUTPUT

genja v25.3.1
- genja

Use the upgrade command to upgrade a single Python tool or all of the installed tools:

BASH

# Upgrade a single tool
$ uv tool upgrade genja

# Upgrade all installed tools
$ uv tool upgrade --all

To remove a tool, use the uninstall command:

BASH

$ uv tool uninstall genja

Challenge

What happens if you run uvx jupyter notebook in your terminal?

Show me the solution

You should see a Jupyter notebook running in your web browser. The file browser for the notebook shows the contents of the directory where the uvx command was run. This is the easiest way to run a Jupyter notebook to explore Python code.

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 command.
With uv, Python tools can be easily installed on any operating system.