Python package managers let you install and manage dependencies—like NumPy, pandas, and so on—right from your terminal.
In this article, you will learn how to use uv—an extremely fast Python package manager.
Prerequisites
To get the most out of this tutorial, you will need to:
Know how to execute commands in your terminal,
Be familiar with basic Python development/scripting.
Table of Contents
Why Should You Use uv?
uv is a free and open-source Python project management tool. Written in Rust, uv is fast and easy-to-use. It has become a standard package manager for modern Python development. You can also use it to manage your virtual environments, making it a good alternative for pip and venv.
Speed tests have shown that uv is faster than other popular package managers when it comes to installing dependencies.
How to Install uv
To install uv, simply execute the following command in your terminal:
For Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh
For Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
How to Set up a Project with uv
To start a new project with uv, run the following command:
uv init freecodecamp-project
This creates the folder /freecodecamp-project in your working directory with the following structure:
├── .gitignore # hidden text file that lists files to be ignored by git
├── .python-version # hidden text file that keeps record of your Python's version number
├── README.md
├── main.py
└── pyproject.toml
README.md is a markdown file, which you can use to communicate information about your project (just as a repository README file on GitHub). pyproject.toml is the configuration file for your project. You can edit it to change your project’s name, version and description. It also keeps track of dependencies you add to project. Last but not least, main.py is where you put your Python code.
Commonly Used uv Commands
Before you can run any uv commands, move your terminal into your project folder:
cd freecodecamp-project
How to Add a Dependency
To add a dependency (for example, NumPy), run:
uv add numpy
# or if you need a specific version
uv add 'numpy==2.3.0'
This automatically adds a virtual environment and a .lock file with a new entry:
├── .venv # hidden folder inside of which your required packages will be installed
└── uv.lock
The .lock file keeps record of the exact versions of your dependencies and their required packages. You should never modify it directly.
How to Remove a Dependency
To remove a dependency, run:
uv remove numpy
This will also remove the corresponding entry from the .lock file.
How to Run Python Code
To run your Python script, execute:
uv run main.py
This will run the code inside the created virtual environment with the installed dependencies in one step! That is, you don’t need to explicitly activate the virtual environment and then run your code.
How to Move Your Project
Sometimes you may want to move your project to another machine. Maybe you want to share it with colleagues, or set it up on a production server. Getting to run your code on another machine has never been easier than with uv. You can simply copy your project folder to the destination environment and run the following command in the destination terminal:
uv sync --locked
This installs the exact versions of your project dependencies!
How to Add and Run Tools
Sometimes you may need tools like ruff, a Python linter (code formatter), which you can add just like any other dependency to your project:
uv add ruff
To run an installed tool, execute:
uv run ruff check
How to Run Tools Without Adding Them to Your Project
Sometimes you may not want to add tools to your dependencies. For example, because you just want to make one-off checks. uv has got you covered with tool run. Simply run:
uv tool run ruff check
# or equivalently
uvx ruff check
This will run the tool in an isolated environment independent.
How to Manage Multiple Python Versions
If your system has Python installed, uv will use it. Otherwise, it will automatically install the latest Python version when you execute Python code or create a virtual environment with uv. However, you can also use it to manage multiple Python versions:
# install the latest Python version
uv python install
# install multiple Python versions
uv python install 3.11 3.12
# list all installed Python versions
uv python list
# set the version to be used in the current project (.python-version)
uv python pin 3.11
How to Migrate from pip to uv
uv works as drop-in replacement for pip, meaning that you can use common pip commands with uv. Let’s say you received a requirements.txt file. To install the listed dependencies, you can run:
uv pip install -r requirements.txt
Conclusion
You just learned how to use uv! Before uv, managing dependencies, virtual environments and Python versions had been notoriously cumbersome. As an ML engineer at MLjobs.io, I can safely say that uv has been a game changer. Check out uv's documentation to learn more.