Python environments: uv
uv venv equivalence
uv venv
//is equivalent to
python -m venv .venv
//Creates a sub directory .venv
The -m means
- python a.py
- //runs a file anywhere in python path
- python -m a
- //runs a module in the available modules
uv run a.py behavior
- if .venv exists, uses it as the dependency resolver cache
- if project.toml exists, resolves by installing dependencies into the .venv
- similar to uv pip install
- creates a uv.lock file in the process
- then runs the a.py
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
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.
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.
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
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)
How big a conceptual difference is it to go to uv?
- Not big, a small adjustment if you understand how "uv" works.
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
What is common between venv and uv approach?
- both maintain .venv
- both resolves libraries correctly
- both hell in running the python scripts
- You can use one or the other
What is different?
- uv uses project.toml to do this
- uv also uses uv lock file to keep a record of installed dependencies
- Every command is run with "uv" as the prefix or the main command
How uv is used in python projects a procedural summary
The things you do when you are developing with python
- Create a repo -- to start your project with a root directory
- Write python files there, .py
- Install desired libraries needed by the .py files
- Run the python file
- Set the shell back to its original state if needed
- Look at what libs are installed
- How to uninstall and restart?
See how each of these steps are performed with uv or python
See how each of these steps are performed with uv or python
Few References now
Few References now
it has
- what is it
- how to install
- how to use it
- More focus on using without venv
- Speaks of some relationships with venv
- ......
- Note: it is incomplete
- Especially using venv naturally
- Later article talks about this
It has
- Focuses on compatibility with venv
- Common useful commands
- Brings it closed to how you use uv
- As always references to public uv material
- .....
- Still not a comprehensive one nor a simpler one
- A good one will combine both
it has
- package manager in Rust
- A replacement for Rye
- Astral: Developer tools for the Python like Ruff, Python linter and formatter.
- Single binary
- Expected to start to look like "Cargo for Rust"
it has
- how to install python itself :)
- Run scripts
- Manage project.toml
- run global packages without installing (uvx)
- Full backward compatibility for venv
- ....
- All in all it is beautifully done
Uv in pictures now....
Uv in pictures now....
start with a non python virtual environments
Python native virtual environments
it has
- what are virtual environments
- in pictures
- how to set them up
- how to activate them and deactivate them
- hot pip install
- look up at what is installed
- References
- Finally, general understanding of virtual environments
While at it a few commands
- uv run <script.py>
- uv venv
- uv pip install <package>
- uv pip uninstall <package>
- uv pip sync
- uv lock
- uv pip freeze
- uv cache dir
- uv cache clear
- uvx <tool>
