UV: Python Environment Setup Finally Fixed
From Zero to Running Code in Minutes Using UV, the Modern Python Tool That Replaces pip, venv, and Broken Setup Workflows
When people struggle with Python, it usually is not because of Python itself. The language is easy to read, flexible, and forgiving.
Most frustration shows up before any real code is written. These are things from setting up the environment, creating virtual environments, installing packages, fixing broken paths, dealing with the wrong Python version, or fighting package conflicts is where progress slows down or stops completely.
We used to just use pip and venv for pretty much everything but this is the exact problem that UV is meant to solve.
UV has become my go to and I absolutely love it. I even made you guys a video surrounding UV and how to get it set up that I linked at the bottom of this article!
Every week you’ll be introduced to a new topic in Python, think of this as a mini starter course to get you going and allow you to have a structured roadmap that actually builds to create you a solid foundation in Python. Join us today!
This article is not about theory. It is about helping readers go from an empty folder to a clean, repeatable Python setup using UV, without juggling a bunch of tools or memorizing brittle steps.
By the end, they will not just know which commands to run. They will understand why the order matters and what UV is actually doing for them along the way.
Thank you guys for allowing me to do work that I find meaningful. This is my full-time job so I hope you will support my work by joining as a premium reader today.
If you’re already a premium reader, thank you from the bottom of my heart! You can leave feedback and recommend topics and projects at the bottom of all my articles.
You can get started with Python today with the goal to land a job in the next few months - Join the Masterclass Here.
👉 I genuinely hope you get value from these articles, if you do, please help me out, leave it a ❤️, and share it with others who would enjoy this. Thank you so much!
What UV actually replaces
Before running any commands, it helps to reset how you think about the tooling. UV replaces pip. It replaces venv. It replaces pip tools. It covers most of what people use Poetry for, without forcing you into a heavy or confusing setup. You do not need to glue tools together. UV is the workflow.
The idea is straightforward. A project declares what it depends on. An environment gets created automatically and the same way every time. Package installs are fast and predictable. Version locking is normal, not something you remember to do later.
That is exactly what UV does.
Step 0: Install UV once
You install UV one time per machine, not per project. Think of it the same way you think about git. You do not install git inside every repo.
On macOS and Linux, the official install command is a single line that downloads a prebuilt binary and adds it to your path. On Windows, there is an installer that handles the same thing.
After installing, run:
uv --versionIf that works, you are done. You do not need to install UV again unless you want to update it.
Step 1: Create a new project folder
UV follows one simple rule. One project lives in one folder.
Create a directory for your project and move into it.
mkdir my_project
cd my_projectRight now the folder is empty. There is no virtual environment. There is no config. This is usually where beginners freeze because they are not sure what comes next.
This is where uv init matters.
Learn Python. Build Projects. Get Confident!
Most people get stuck before they even start… But that doesn’t have to be you!
The Python Masterclass is designed to take you from “I don’t know where to start” to “I can build real-world Python projects” — in less than 90 days.
👉 I’m giving you my exact system that’s been proven and tested by over 1,500 students over the last 4+ years!
My masterclass is designed so you see your first win in less than 7 days — you’ll build your first working Python scripts in week one and finish projects in your first month.
The sooner you start, the sooner you’ll have projects you can actually show to employers or clients.
Imagine where you’ll be 90 days from now if you start today.
👉 Ready to get started?
P.S. — Get 20% off your First Month with the code: save20now. Use it at checkout!
Step 2: Initialize the project with uv init
This is the missing step most people overlook.
uv init tells UV, this folder is a Python project. All you have to do is run:
uv initThis creates a pyproject.toml file in the directory. That file becomes the single source of truth for the project. It holds metadata, dependencies, and Python version requirements.
Nothing gets installed yet. No environment is created yet. That is on purpose. UV avoids doing work until it is actually needed.
If you open pyproject.toml, you will see a clean and minimal file. This replaces the old mess of requirements files and custom scripts. From this point forward, UV reads from and updates this file automatically.
Step 3: Add your first dependency
This is where UV starts doing real work.
Instead of manually creating a virtual environment and then running pip install, you do one thing.
uv add requestsThat single command handles everything in the right order.
UV figures out the dependency tree for requests.
It creates an isolated environment if one does not already exist.
It installs requests and its dependencies into that environment.
It updates
pyproject.toml.It creates or updates a
lockfilewith exact versions.
You did not activate anything. You did not touch paths. You did not wonder where packages went. The environment now exists and is ready to use.
This is the big mental shift. You do not manage environments directly anymore. They are created as a result of declaring dependencies.
Step 4: Run Python inside the UV environment
At this point, the obvious question comes up. How do you run Python now?
UV gives you two clean options. To start an interactive shell:
uv run pythonIf you want to run a script:
uv run python main.pyThere is no virtual environment to activate. uv run always uses the correct environment. For beginners especially, this removes a whole class of quiet mistakes that are hard to debug.
Step 5: Add more dependencies as the project grows
As your project grows, adding packages always looks the same.
uv add numpy
uv add pandas
uv add matplotlibEach command updates dependencies and the lockfile in a controlled way. UV handles compatibility so you do not have to think about resolution rules.
This also makes the project self documenting. Anyone who opens pyproject.toml can see exactly what the project depends on.
Step 6: Add development-only dependencies
Real projects usually need tools that are not part of the app itself. Test frameworks, linters, formatters, and type checkers should not be global installs or mixed with production dependencies.
UV handles this with dependency groups.
uv add pytest --group devNow pytest is clearly marked as a development dependency. It lives in the same environment but is logically separated. This becomes important as projects grow or when deployment enters the picture.
Step 7: Install dependencies on another machine with uv sync
This is where UV does really good. A teammate clones the repo. You open the project on a new laptop. A CI system needs to install dependencies.
The command is always the same.
uv syncUV reads pyproject.toml and the lockfile and installs exactly what is specified. Nothing more. Nothing less.
This is how you avoid the classic works on my machine problem without long setup docs.
Step 8: Update dependencies intentionally
Dependencies should not change by accident. UV pushes you toward being intentional.
When you want to update, you run:
uv updateUV re-resolves dependencies within the allowed limits and updates the lockfile. If something breaks, you know exactly when it happened and why.
Updates become a conscious choice instead of a surprise.
Step 9: Enforce Python version consistency
One of the most common hidden issues in Python projects is version mismatch. Code works on Python 3.11 and quietly fails on 3.9.
UV lets you define Python version requirements directly in the project. If someone tries to use an unsupported version, UV fails early instead of letting subtle bugs slip in.
For teams and learners, this alone saves a huge amount of time and frustration.
Why this order matters
The order you called out is not just for looks. It is the foundation of the whole workflow.
You start by initializing the project so the tools know what they are working with.
You add dependencies before thinking about environments because environments exist to support dependencies, not the other way around.
You sync before running code because being able to reproduce the setup matters more than running something quickly.
A lot of traditional Python setups flip this order, and that is why they feel brittle. UV matches the order to how projects actually work in real life.
Why this works so well
Beginners do not struggle because Python is difficult. They struggle because the setup is loud and punishing. UV cuts out the noise.
There is one tool. One config file. One way to install packages. One way to run code. That alone removes a huge amount of mental strain.
At the same time, UV does not hide the important ideas. Virtual environments still exist. Locking dependencies still matters. Version rules still apply. They just show up naturally instead of all at once.
For experienced developers, UV is about speed, reliability, and confidence.
Installs are fast.
Dependency resolution is predictable.
CI setups are simpler.
Local and remote environments behave the same way.
Most importantly, the tooling gets out of the way and lets you focus on the work.
👉 My Python Learning Resources
Here are the best resources I have to offer to get you started with Python no matter your background! Check these out as they’re bound to maximize your growth in the field.
Zero to Knowing: Over 1,500+ students have already used this exact system to learn faster, stay motivated, and actually finish what they start.
P.S - Save 20% off your first month. Use code: save20now at checkout!
Code with Josh: This is my YouTube channel where I post videos every week designed to help break things down and help you grow.
My Books: Maybe you’re looking to get a bit more advanced in Python. I’ve written 3 books to help with that, from Data Analytics, to SQL all the way to Machine Learning.
My Favorite Books on Amazon:
Python Crash Course - Here
Automate the Boring Stuff - Here
Data Structures and Algorithms in Python - Here
Python Pocket Reference - Here
🎬 UV Guide Video
Wrapping it up
UV is not interesting because it is new. It is interesting because it makes Python feel boring again, in a good way.
You initialize the project once with uv init. You add dependencies as you need them. You sync when you move to a new machine or environment. You run your code without extra steps.
That is really all there is to it.
When setup fades into the background, learning and building take center stage. That is what UV gives your readers.
Hope you all have an amazing week nerds ~ Josh (Chief Nerd Officer 🤓)
👉 If you’ve been enjoying these lessons, consider subscribing to the premium version. You’ll get full access to all my past and future articles, all the code examples, extra Python projects, and more.