Package & Virtual Environment Management

image

This tutorial walks you through installing and using Python packages.

It will show you how to install and use the necessary tools and make strong recommendations on best practices. Keep in mind that Python is used for a great many different purposes, and precisely how you want to manage your dependencies may change based on how you decide to publish your software. The guidance presented here is most directly applicable to the development and deployment of network services (including web applications), but is also very well suited to managing development and testing environments for any kind of project.

Make sure you've got Python

Before you go any further, make sure you have Python and that it's available from your command line:

$ python3 --version

You should get output like Python 3.13.x. If you do not have Python, see the Installing Python section of this guide.

If you're a newcomer and you get an error like NameError: name 'python' is not defined, it's because this command is intended to be run in a shell (also called a terminal or console), not inside the Python interpreter.

uv is a fast, all-in-one Python package manager and project tool written in Rust. It replaces pip, virtualenv, pip-tools, pipx, poetry, pyenv, and more — with a single binary that's 10-100x faster than the tools it replaces.

If you're familiar with Node.js's npm or Rust's cargo, it's similar in spirit to those tools.

Installing uv

macOS / Linux:

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

Windows:

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

With pip:

$ pip install uv

Creating a Project

$ mkdir myproject && cd myproject
$ uv init

This creates a pyproject.toml and a .python-version file. Now add a dependency:

$ uv add requests

uv will:

  1. Create a virtual environment automatically (.venv/)
  2. Resolve and lock all dependencies (uv.lock)
  3. Install everything

Using Installed Packages

Create a main.py file:

import requests

response = requests.get('https://httpbin.org/ip')
print(f'Your IP is {response.json()["origin"]}')

Run it with uv:

$ uv run python main.py

Using uv run ensures your script runs within the project's virtual environment with all dependencies available.

Adding and Removing Dependencies

$ uv add httpx          # add a dependency
$ uv add --dev pytest   # add a development dependency
$ uv remove httpx       # remove a dependency

All changes are reflected in pyproject.toml and uv.lock.

Running Commands in the Environment

$ uv run pytest         # run any command in the virtual environment
$ uv run python app.py  # run a script with dependencies available
$ uv shell              # activate the virtual environment in your shell

pipx: Install Global CLI Tools

pipx installs and runs Python CLI applications in isolated environments. Use it for tools you want available system-wide:

$ uv tool install black      # install a tool globally
$ uv tool install ruff
$ uv tool run ruff check .   # run without installing

Lower Level: venv

Python 3 includes the built-in venv module for creating virtual environments. This is useful when you don't need a full project setup.

Basic Usage

  1. Create a virtual environment:
$ python3 -m venv .venv
  1. Activate it:

macOS / Linux:

$ source .venv/bin/activate

Windows:

> .venv\Scripts\activate

The name of the active environment appears in your prompt (e.g., (.venv)).

  1. Install packages:
$ pip install requests
  1. Save dependencies:
$ pip freeze > requirements.txt
  1. Install from a requirements file:
$ pip install -r requirements.txt
  1. Deactivate:
$ deactivate

To delete a virtual environment, simply remove its folder:

$ rm -rf .venv

Remember to exclude the virtual environment folder from source control by adding .venv/ to your .gitignore.

direnv

direnv automatically activates a virtual environment when you cd into a project directory. Add this to your project's .envrc:

source .venv/bin/activate

Install on macOS:

$ brew install direnv

Then follow the setup instructions for your shell.