From npm to uv: A Node.js Developer's Guide to Python Project Setup

If you’re a Node.js developer stepping into the Python world, you’re probably used to the speed and simplicity of tools like npm, pnpm, or yarn. You run npm install, your dependencies pop into node_modules, and you’re off to the races. Then you encounter Python and hear about pip, venv, virtualenv, pipenv, poetry… and it all feels a bit… fragmented.

What if I told you there’s a tool that brings a familiar, unified, and blazingly fast experience to Python, much like the modern tools in the JavaScript ecosystem?

Enter uv.

What is uv? The npm for Python You’ve Been Wishing For

uv is an extremely fast Python package installer and resolver, written in Rust by the same folks behind the ruff linter. Think of it as a single binary that aims to replace pip, pip-tools, and venv.

For a Node.js developer, the pitch is simple:

• It’s Fast: Like, esbuild or swc fast. It uses a global cache and parallel processing to make dependency installation significantly quicker.
• It’s an All-in-One Tool: It handles installing packages, running commands, and managing virtual environments. No more juggling different tools. It’s like npm and npx rolled into one.
• It’s Familiar: The concepts map almost directly to what you already know from npm.

Step 1: Installing uv

First things first, you need Python installed. Once that’s sorted, installing uv is a one-liner.

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

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

This single binary is all you need.

Step 2: Creating a Virtual Environment (Your New node_modules)

In Node.js, dependencies are installed locally into a node_modules directory by default. This is great for project isolation. Python’s answer to this is the “virtual environment,” which is essentially a folder containing a copy of the Python interpreter and all the packages for a specific project.

With uv, creating one is trivial.

# Create a project and move into it
mkdir my-python-project
cd my-python-project

# Create a virtual environment named .venv
uv venv

This creates a .venv folder. Think of .venv as your new node_modules directory. It’s where all your project-specific Python packages will live, keeping your global space clean.

Just like .gitignore includes node_modules, you should add .venv to your .gitignore file.

Step 3: Activating the Environment

This is one small step that’s different from the Node.js workflow. To use the tools and packages inside your virtual environment, you need to “activate” it.

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Your terminal prompt will change to indicate that you’re now “inside” the virtual environment. Now, any python or pip command will use the versions inside .venv.

Step 4: Installing Packages (The npm install Moment)

Ready for that familiar npm install feeling? Let’s install a package. The requests library is the axios of the Python world, so we’ll start there.

# This is like `npm install requests`
uv pip install requests

You’ll see uv resolve and install the package with incredible speed. If you inspect the .venv directory, you’ll find requests and its dependencies in there, just like you’d find packages in node_modules.

To install a dev dependency, you can add it to a specific requirements file, similar to devDependencies. For now, let’s stick to the basics.

Step 5: Saving Dependencies (package.json and requirements.txt)

In Node.js, your dependencies are automatically saved to package.json. uv follows the classic Python pattern of using a requirements.txt file.

You can generate this file after installing your packages.

# This is like creating a snapshot of your dependencies
uv pip freeze > requirements.txt

Your requirements.txt will now look something like this:

# requirements.txt
certifi==2023.11.17
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.1.0

This file is your package.json’s dependencies list. Anyone else on your team can now install the exact same dependencies using this file.

# This is like running `npm install` after cloning a repo
uv pip install -r requirements.txt

Step 6: Running Tools with uvx (The npx Equivalent)

One of the best parts of the Node.js ecosystem is npx, which lets you run a package’s binary without installing it globally.

uv has a direct equivalent: uvx.

Let’s try it with cowsay, a classic command-line toy.

# This is like `npx cowsay "Hello from uv!"`
uvx cowsay "Hello from uv!"

uvx will temporarily install cowsay, run the command, and then clean it up. It’s perfect for running project-based tools like linters (ruff), formatters (black), or web servers (uvicorn) without polluting your environment.

Tying It All Together: A Node.js to uv Cheat Sheet

Node.js (npm)	Python (uv)	Description
npm install <pkg>	uv pip install <pkg>	Installs a package to the local environment.
npm install	uv pip install -r requirements.txt	Installs all dependencies from the project file.
package.json	requirements.txt	The file that lists your project’s dependencies.
node_modules/	.venv/	The local, isolated folder containing dependencies.
npx <cmd>	uvx <cmd>	Executes a package command without a permanent install.
npm init -y	uv venv	Initializes a new project environment.

Conclusion

The Python ecosystem is powerful, but for a Node.js developer, the tooling can sometimes feel like a barrier. uv changes that. By providing a single, cohesive, and lightning-fast tool, it offers a developer experience that feels right at home.

So next time you start a Python project, give uv a try. You might just find the npm-like workflow you’ve been looking for.