Python environments: uv

android Android

web Web

4-Aug-25 (Created: 4-Aug-25) | More in 'Python'

satya - 6/29/2025, 8:38:36 AM

is there a diff between creating a python venv through venv or uv venv?

satya - 6/29/2025, 8:45:18 AM

My github write up on venv

satya - 6/29/2025, 8:47:29 AM

My github article: previous notes on uv

satya - 6/29/2025, 9:36:14 AM

uv venv equivalence



uv venv

//is equivalent to

python -m venv .venv

//Creates a sub directory .venv

satya - 6/29/2025, 9:37:26 AM

The -m means

satya - 6/29/2025, 10:02:36 AM

uv run a.py behavior

satya - 6/29/2025, 10:03:38 AM

In other words you can do this


//create a .venv for keeping vscode happy
uv venv

//ensure there is a project.toml and run your .py file
uv run a.py

satya - 8/1/2025, 9:27:33 AM

Understanding uv: Background of how python programs are executed

Yes! it is a package manager. That postpones the discussion further...
Traditionally python programs, or more like scripts are run with python.exe and the name of the python script file like a.py
Any libraries that a.py uses are resolved using globally installed python libraries
That causes conflicts as all scripts are sharing a common library environment
This variation can go not only to the libraries but the version of python.exe itself.

satya - 8/1/2025, 1:02:03 PM

Enters venv from python

Natively python answers this with a sub directory called .venv under the project root.
It relies on adjusting the command line paths and settings to store all new installed libraries into that venv directory
It provide a batch file called venv/activate.sh to setup the environment variables in the shell
Once you activate it, all subsequent python executions will use the venv for path resolution.
Especially the python pip install, will installs the subsequent libs into the venv sub directory.
When you no longer wants to use the specialized enviornment in the shell you call deactivate or just close the shell.

satya - 8/1/2025, 1:08:37 PM

What is wrong with it that we need uv?

At its core, you are temporarily changing the shell to simulate a virtual environment
There is no explicit registry that is managed to recreate the library environment when it is transported.
You typically do that by doing a pip freeze to list the total installed "libraries" in venv and check it in, usually something like a "requirements.txt", a list of all libraries
That is a manual step
Also you have to remember to activate and deactivate the shells
It does not rely on a project definition file like your-project.toml that explicitly controls how things and dependencies are setup.
In other words you can have two projects that can share that venv and there isn't a way to know which shares what
So it relies on the programmer to manage that meta data

satya - 8/1/2025, 1:10:50 PM

is then python venv approach bad?

It is quite workable
it is simple enough
Most tools like vscode assume venv and pythons approach of running python programs. They are not yet fully programmed for "uv" like behavior
It works quite well
The need to go to "uv" is a small enhancement (or big if a particular aspect of uv makes your life simpler)

satya - 8/1/2025, 1:11:15 PM

How big a conceptual difference is it to go to uv?

satya - 8/1/2025, 1:19:48 PM

so how does uv work?

Practically speaking you run every python script using "uv script args"
This includes pip install, a.py, or any script
You are telling "uv", like an agent, hey, run this python code for me!!
uv then decides to run that code using the python interpreter by picking the right path and the right libraires using a config file for that project context.
This project context is maintained in the root of the repo as "project.toml"
This file contains the project dependencies for all the script files in that project
uv will install all the dependencies from project.toml into the .venv sub directory, by creating one if it doesn't exist, the venv directory itself
It does not need to set the activation
It does it programmatically at run time just for that script
Your shell is untouched
Further it creates uv lock file that contains all the long list of resolved dependencies
this file can be checked in along with project.toml into github
the venv then can be recreated just using the project.toml spec
In other words the meta data about your project is captured in project.toml