UV Global Guide

Using uv Globally and Simply

Nov 08, 2025

uv (https://docs.astral.sh/uv) is a Python project and package management solution built in Rust. It is fast, fully featured, and well organized. In the words of the authors, uv is:

A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine,
virtualenv, etc...

Having struggled some to install a user-based version of python with uv, we found that the best way to use uv per user account, is to go with uv’s nature and create a global project. We explore how to setup this environment using the standard uv project paradigm.

Note

uv has a concept of (global) tools that are installed outside of our global project scenario.

We sidestep this mechanism for now, and briefly discuss them later.

Our solution is to install a project via uv, call it global, populate it will whatever tools and libs you need, then use that global project/environment to run your many python dependent scripts for your entire user account.

The reasons why we think this method is useful:

Consistency: You use uv as you normally would for any other project
It is easy to understand and use
Less chaos compared to using global configurations or other tools
It doesn’t interfere with any other uv projects

Here is the outline of how it works:

Install uv as usual but in folder ~/.uv
Inside the uv base, ~/.uv/, create a project/folder named global
Activate that environment using ~/.uv/.venv/bin/activate
When in that project, add all tools that you need for your global environment using uv

See https://github.com/astral-sh/uv/discussions/998#discussioncomment-10385800 for background motivation.

Install Steps

install uv:

curl -LsSf https://astral.sh/uv/install.sh \
   | env UV_INSTALL_DIR="$HOME/.uv" sh

Make uv active
```
source "$HOME/.uv/env"
```
Create a global uv environment:
```
uv init $HOME/.uv/global --python 3.12
```
Sync that new global:
```
cd ~/.uv/global ; uv sync
```
Initialize that global env:
```
. ~/.uv/global/.venv/bin/activate
```

Add dependencies etc… :

cd ~/.uv/global       # We repeat this just in case you forgot
uv add tabulate yfinance colored termcolor

Initialize at Login

Once you have all this in place, you probably want to know how to initialize all this at login:

Activate the global env
```
. ~/.uv/global/.venv/bin/activate
```

Optionally activate uv: You don’t need it just to run the global environment, but you need it to “add” libs/programs in global

source "$HOME/.uv/env"   # Exposes the *uv* command
cd ~/.uv/global          # You need to be here to add stuff.
uv add Sphinx ansible    # Example: adds deps to pyproject.toml and installs em

Automating the Environment at Login

You can automate this global Python environment at login in many ways. One way to do this is to create a small script in ~/bin and execute that at login:

Here is a short env script, ~/bin/uv.sh to do all the activation:

# File: ~/bin/uv.sh
. "$HOME/.uv/env"
. ~/.uv/global/.venv/bin/activate

Then in your .bashrc:

# .bashrc
if [[ -f ~/bin/uv.sh ]]; then
   source ~/bin/uv.sh
fi

Optionally you can invoke the script manually:
```
source ~/bin/uv.sh
```

Adding Packages to Global

Because we are using a project environment as a user-wide python, we need to be in the project folder to add packages. For example:

cd ~/.uv/global
uv add yfinance

UV Tools

uv has a concept of tools (https://docs.astral.sh/uv/concepts/tools/) which are truly global to the user, and does not use our global setup. Tools get installed to $HOME/.local/bin where they are visible regardless of any python environment. For example:

# Make sure no python environment is active:
deactivate
# Install a tool using uv:
uv tool install ruff
ruff --version

You should see that ruff works without any python environment.

Final Words

We are only using a tiny part uv in order to maintain a clean python environment. uv has many many more features you should check out at: https://docs.astral.sh/uv/