UV - Python package & project manager
Introduction
UV is awesome, UV is great, UV is life! Yeah UV is the best Python tooling as drop-in replacement for similar tools such as pip and conda. It is by far the least painful package and project manager in the Python ecosystem. It has been quite hassle-free using UV and in this article we are going to learn how easy it is to use UV.
What is UV?
Taken from the documentation:
A drop-in replacement for common pip workflows. An end-to-end solution for managing Python projects, command-line tools, single-file scripts, and even Python itself. It's Cargo, for Python: a unified interface that's fast, reliable, and easy to use.
How to use
Installation
- Linux and macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh - Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
First : uv init
This command will initialize the creation of a new project. Take a look at the chain of commands below:
mkdir my_project && cd my_project --> create my_project directory and set it as current directory.
uv init --> initialized a new project inside the my_project directory.
Once you've done both commands above, you'll see you have new files inside "my_project". The most important file is the pyproject.toml (project's configuration file).
Second : modify pyproject.toml
Use whatever text/code editor to edit pyproject.toml, inside you'll find basic configuration:
[project]
name = "my_project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
Main highlights on these fields: requires-python and dependencies .
You can modify these fields according to your needs, for example a good rule of thumb is to have N-1 version: meaning if the most recent Python version is 3.12 then you'll use 3.11.9 as the most updated version of Python 3.11.
Next let's say you want to build a website and you need to do some data processing, you'll need Flask and Pandas for the project. Modified pyproject.toml:
[project]
name = "my_project"
version = "0.1.0"
description = "My project description is here!"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
"flask>=3.0.3",
"pandas>=2.2.3",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
Note I put flask>=3.0.3 and pandas>=2.2.3 as it is best practice to be specific with your dependency requirements. You can put whatever versions you need for the project.
Third - uv sync
The last part is very easy you only need to run the command: uv sync
This command will tell UV to read from your pyproject.toml and prepare the neccessary requirements: it will create a virtual environment and then install the correct Python version for you along with the required libraries (in this case: Flask and Pandas).
Fourth - activating the virtual env
Use this command to activate your project's venv:
. .venv/bin/activate
Pay attention there's a dot space dotvenv in the command above! If you do this correctly, you will see my_project py in your terminal which means you have successfully activated the project's virtual env.
Bonus - install Python
You can initiate Python installation using these commands:
uv python list --> to see which versions are available.
uv python install 3.9.19 --> install the selected Python version, in this example: 3.9.19
Conclusion
That's it! With those simple 4 steps you can start write Python programs using the libraries you need in a Python version you requested. And all that goodies are inside a virtual env so it won't break your PC if you did something wrong.