UV is a powerful package manager for Python. UV can supplement or even replace other tools like pip, conda, and venv. However it works a little differently so here are some notes to help with usage. Note that I have mostly been using UV on Windows but it also works on Mac and Linux.
Getting Started
First of all you will need Python installed. You can download and install Python from https://www.python.org/downloads/ . Next you will need to get UV itself. This can be done with pip install uv and there are other methods as well.
uv init
Now lets use UV to set up our project environment. To do this navigate to the folder where you want to place your project folder. Next type uv init project-name . This will create a folder called project-name inside the folder with the following structure:
├── /.git
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.mdAs you can see, a really nice feature of using UV to set up a project is that it also sets up all the requisites for a git repository. This means that you can then easily push your new project up to Github or another provider rather than needing to set that up as a separate step.
uv venv
One thing that the uv init command does not set up is a virtual environment. To do this navigate into your new project folder and type uv venv . This will set up a .venv folder with a virtual enviroment in it which is compatible with the old venv virtual environment creator. The python version will be that specified in .python-version. You can also specify python versions and the environment name if you wish, the docs are here. You can also use uv python install to install the latest version of Python if you get an error when trying to create the virtual environment, then use uv python update-shell to add it to your PATH. As with traditional venv virtual environments you can activate your new environment with .venv\Scripts\activate. You can then run uv pip list, but you will find that your virtual environment has not got any libraries in it.
Adding Packages
To add packages to your virtual environment, make sure is is activated. You could then use the command uv pip install package-name to install the required package. A good thing here is that UV tends to be a lot quicker at resolving dependencies that pip is so setting up your environment should go faster.
However this installation approach has a problem. While it installs the packages it does not add them to pyproject.toml or uv.lock. This means that when you next run uv sync, these packages will be removed from your virtual environment. This can be useful if you were unsure if a given package was going to be required but can be infuriating if you did want a package and accidentally remove it at next sync. Therefore once you are sure that you are going to want to retain a package as part of your project you should instead use uv add package-name , This will both install the package and also add it to the files UV uses for project dependencies. These dependency files are in some ways UV’s secret sauce because they allow anyone downloading your project to use them to rapidly set up their environment in the same way you have.
Running Python Files
So you have completed the basic UV project setup, congratulations. You can then now your python files (for example main.py which UV sets up when you use uv init) with the command uv run main.py . Be aware that this command looks in pyproject.toml and sets up your environment if it is not already set up. It is therefor e important that pyproject.toml and .python-version have compatible python versions, this will be true by default after first initialisation but if you make modifications this can lead to issues.
Other Features
UV has a lot of other features too like running tools and viewing dependency trees. More information on the useful things it can do can be found here
