A hygienic Python setup for 2025

Updated on March 7, 2025 · 4 min read

Since a few years, whenever anyone asks me for advice on setting up a Python environment, I always point them to this lovely blog post.

In the past few months, however, I ended up switching to uv, brought to you by the same brilliant minds behind Ruff.

And after trying it out, experiencing how smooth and fast it is, and wanting to share it with some friends, I thought I’d write a quick guide in the same vein as Ben’s post.

That guide remains a great reference, and if that setup works for you, you should stick with it!

But if:

• You’re tired of Python dependencies trying to take over your system.
• You want to avoid the dreaded pip install in your terminal.
• You are facing issues when installing some Python packages using Poetry (looking at you PyTorch 👀).
• You need to look hip and cool in front of your friends.

Then this is for you!

I won’t go into the details, this is more of a quick-start to get you up and running with a hygienic Python setup. I’ll leave all the links pointing to the official documentation instead, in case you want to dive deeper.

What we are replacing

• Pyenv: uv now manages Python versions.
• Poetry: uv uses pyproject.toml to manage projects.
• Pipx: uv has a tooling system that run tools in isolated environments.

Installing uv

Duh! Everything else depends on it.

It’s a Rust binary, so the nice thing is that you don’t need anything else on your system.

There are a bunch of options to install it, and I won’t tell you which one to choose (I’m not your mom).

But I would just say that the easiest way is to use the official installer script.

macOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternatives

I’d be a bad person if I didn’t mention that you can also install it using Cargo, Homebrew, WinGet, Scoop, (and even pip, of course!), or you can just download the binary and put it in your PATH…

Considering the scope of this guide however, and unless you know what you’re doing (but then, why are you reading this?), DO NOT USE PIP!

You’re going to be building up a house of cards, and end up in a world of pain once it inevitably falls apart.

If you do know what you’re doing and would rather use one of those options above, do take a look at the official installation instructions.

Personally, I used Homebrew on macOS, but you do you.

Start your first project

We aren’t wasting time here: you can jump straight into creating your first project.

uv init your-new-project  # this will install the latest Python if you don't have it
cd your-new-project
uv run hello.py     # now it will create a virtual environment and run the script

Installing dependencies

And finally, we can start adding dependencies to this project without polluting our system.

uv add requests

Tools

You may still need to install some tools outside of a specific project. For example, we mentioned Ruff earlier.

If you need to run something just once, you can do this from any directory:

uvx ruff  # expands to: uv tool run ruff

but if you then decide you want to install it globally:

uv tool install ruff
which ruff  # will show you where it was installed

Conclusion

I won’t even bother mentioning how much faster this is compared to Poetry + Pyenv + Pipx + Pipenv + Conda + Docker + … both in terms of setup (you just need to install one thing!) and execution (thanks to our overlord Ferris the crab).

I hope you find this setup as useful as I did, and that it helps you keep your system clean and your projects organized.

Happy coding!

PS: I’m not affiliated with Astral, I just really like their tools. Also, have you heard they’re working on a static type checker? I can’t wait to try it out!