Supercharge Python Development: Get Started with ‘uv run’

Give Your Python Code a “Superpower” with This New Trick!

Hey everyone, John here! Welcome back to the blog where we break down the latest in AI and tech into plain, simple English. Today, we’ve got something really exciting for anyone who’s ever been curious about programming in Python. We’re going to talk about a tool called uv, and specifically, a magical command called uv run.

Imagine you want to build a model airplane. Normally, you’d have to clear your desk, get out all your tools, find all the right parts, and only then could you start building. It’s a lot of setup. What if you had a magic box that, when you told it “build the plane,” would instantly create a temporary workspace, fetch all the tools and parts for you, let you build the plane, and then vanish, leaving your desk perfectly clean? That’s kind of what uv run does for your Python code!

I’ve got my trusty assistant, Lila, here with me to help us sort through this.

“Hi, John! I’m ready. I’ve heard Python can be complicated with all the ‘setup’ involved, so I’m excited to see how this makes it easier.”

You’ve got it, Lila. Let’s dive in!

So, What Does ‘uv run’ Actually Do?

At its core, uv run is a command that executes a Python program. Let’s say you have a file named my_first_program.py. To run it, you would just type this into your command line:

uv run my_first_program.py

Simple, right? But here’s the catch. This basic command only works if your program is completely self-sufficient, meaning it doesn’t need any extra tools or libraries that aren’t already installed on your computer. If your program needs a special tool to do complex math or draw a chart, it will stop and say, “I can’t find what I need!”

This is where the real magic of uv run comes into play.

Giving Your Code the Tools It Needs on the Fly

Most useful Python programs rely on other pieces of code written by other people. These are called dependencies. Think of your code as a recipe. The dependencies are the ingredients, like flour, sugar, or a special kind of chocolate. Without them, your recipe won’t work.

“Okay, John, hold on. What exactly are ‘dependencies’? And you mentioned a tool for math? Can you give an example?”

Great questions, Lila! A dependency is just a pre-written package of code that your program depends on to do a specific job. For example, instead of writing thousands of lines of code to do complicated math from scratch, you can just use a dependency called NumPy. It’s a super popular library that’s an expert at handling numbers and equations.

With uv run, you don’t need to permanently install NumPy on your computer just to try it out. You can tell uv run to grab it for you temporarily using a special instruction called --with. It looks like this:

uv run --with numpy my_first_program.py

When you run this, uv fetches NumPy, makes it available to your program in a temporary little bubble, runs your code, and then it’s all gone. No mess!

What if you need more than one tool? Easy! Just separate them with a comma:

uv run --with numpy,matplotlib my_first_program.py

And if you need a specific version of a tool (maybe an older one that works with your old code), you can “pin” it like this:

uv run --with numpy==2.0 my_first_program.py

This is like telling the grocery store you don’t just want any chocolate, you want the “Baker’s Best, 2024 Edition” chocolate. It gives you precise control.

What’s Happening Behind the Curtain? The Magic of Caching

So when you use the --with command, what is uv actually doing? It’s a pretty smart process:

• Step 1: It Goes Shopping. uv connects to a place called PyPI to find the package you asked for (like NumPy).
• Step 2: It Downloads. It downloads the package to your computer.
• Step 3: It Caches. This is the clever part. It stores a copy of that downloaded package in a special folder on your computer called a cache.
• Step 4: It Runs. It then runs your program using the freshly downloaded package.

“Wait a minute, John. What is this ‘PyPI’ you mentioned? And what’s a ‘cache’?”

Excellent questions, Lila. Let me clarify:

• PyPI (Python Package Index): Think of this as a gigantic, official online supermarket or app store exclusively for Python. It’s where developers all over the world share their tools (like NumPy), and it’s where tools like uv go to get them.
• Cache: The cache is like a pantry in your kitchen. The first time you need a special ingredient (like coconut flour), you have to go to the store (PyPI) to get it. This takes time. But once you have it, you store it in your pantry (the cache). The next time a recipe calls for coconut flour, you can just grab it from the pantry instantly instead of driving all the way to the store again.

This caching is why uv run is so fast. The first time you ask for a package, there might be a short delay while it downloads. But every time after that, uv pulls it from your local cache, and your program starts almost instantly!

And if you ever want to clear out your “pantry” and start fresh, you can use the command uv cache clean. Or, if you want to force uv to ignore the pantry and go straight to the online store for the freshest version, you can add the -n flag.

Using ‘uv run’ with Projects on Your Computer

This tool isn’t just for running single files. It’s also fantastic for working with bigger projects you might have downloaded, for instance, from a code-sharing site like GitHub. These projects usually come with a special file called pyproject.toml.

“Okay, another new term! What does a pyproject.toml file do, John?”

Think of the pyproject.toml file as the instruction manual and list of ingredients on the front of a board game box. It tells uv everything it needs to know about the project: its name, what dependencies it needs, and what its main functions are. It’s the project’s main configuration file.

When you are in a project folder that has one of these files, you can use uv run in a few cool ways:

• Run a specific part of the project: If the project has a command-line tool named proj_cmd, you can run it directly with uv run proj_cmd.
• Run by its “entry point”: Sometimes, developers create shortcuts to run their programs. These are called entry points. They are like a pre-programmed “Start” button for the project. If the developer set one up, you can use uv run to launch it.
• Open a “workspace”: You can even type uv run python. This command essentially says, “Set up the temporary environment with all the tools this project needs, and then just give me a direct line to Python so I can experiment myself.” It’s like having the magic box set up the entire workshop for you and then letting you play around with all the tools freely.

My Final Thoughts

As someone who has spent countless hours setting up development environments, a tool like uv run feels like a breath of fresh air. It removes so much of the boring, repetitive setup and lets you get straight to the fun part: writing code and solving problems. It truly feels like being given a new superpower.

“From my perspective as a beginner,” Lila added, “the idea of not having to ‘install’ something permanently just to try it out is a huge relief. It makes programming feel so much more approachable and less intimidating. It’s like being able to test-drive a car without having to buy it first!”

Well said, Lila. It’s tools like this that make technology more accessible for everyone.

This article is based on the following original source, summarized from the author’s perspective:
Amp your Python superpowers with ‘uv run’