Using uv

Let’s break down how to set up and use a local Python environment with uv after you’ve installed it.

uv aims to be a very fast, drop-in replacement for pip and venv (and potentially other tools like pip-tools). The workflow is similar to using venv and pip, but often faster and integrated.

1. Creating the Virtual Environment

The core command is uv venv. You typically create a virtual environment within your project directory. The standard convention is to name the environment directory .venv.

Navigate to your project directory:
```
  cd /path/to/your/project
```
Create the environment:
```
  uv venv
```
This command creates a directory named .venv in your current location, containing a Python interpreter and necessary scripts.
Specifying a Python Interpreter (Optional): If you have multiple Python versions installed and want to use a specific one for this environment, you can specify it:
```
  # Example: Use Python 3.11 if available
  uv venv -p 3.11

  # Or provide a full path
  uv venv -p /usr/bin/python3.11
```
If you don’t specify, uv will try to find a suitable Python interpreter on your system.

2. Activating the Environment

Activating the environment modifies your shell’s PATH so that commands like python, pip (and uv itself when used for package management within the environment) refer to the versions inside .venv. This isolates your project’s dependencies.

The activation command depends on your shell:

Bash or Zsh (Linux/macOS):
```
  source .venv/bin/activate
```
Fish Shell (Linux/macOS):
```
  source .venv/bin/activate.fish
```
PowerShell (Windows):
```
  .venv\Scripts\Activate.ps1
```
(You might need to adjust your PowerShell execution policy: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser)
Command Prompt (cmd.exe) (Windows):
```
  .venv\Scripts\activate.bat
```

Once activated, you’ll usually see the environment name (e.g., (.venv)) prepended to your shell prompt.

3. Managing Dependencies (Installing Packages)

With the environment activated, you use uv pip commands to manage packages within that specific environment.

Install packages:

  uv pip install requests
  uv pip install "django>=4.0" flask beautifulsoup4

Install from a requirements file: If you have a requirements.txt file:
```
  uv pip install -r requirements.txt
```

Install from pyproject.toml: If your project uses a pyproject.toml file (with dependencies defined under [project] or [tool.pdm], etc., though uv primarily focuses on the standard [project.dependencies]):

  # Installs the package defined in the current directory's pyproject.toml
  uv pip install .

  # Install optional dependency groups if defined (e.g., [project.optional-dependencies])
  uv pip install ".[dev, test]"

Syncing with a requirements file: Use uv pip sync to ensure your environment exactly matches the requirements file. It will install missing packages and uninstall any packages present in the environment but not listed in the file. This is great for reproducibility.
```
  uv pip sync requirements.txt
```
Listing installed packages:
```
  uv pip list
```
Generating a requirements file:
```
  uv pip freeze > requirements.txt
```
This captures the currently installed packages and their exact versions into requirements.txt.

4. Deactivating the Environment

When you’re finished working on the project, you can deactivate the environment to return to your global Python context:

deactivate

This command works across all the shells mentioned above.

Files and Scripts Involved

.venv Directory: This is the main directory created by uv venv. It contains:
- bin/ (or Scripts/ on Windows): Contains the Python executable for the environment, the activate scripts, and executables installed by packages (like flask, django-admin, etc.).
- lib/ (or Lib/ on Windows): Contains installed Python packages.
- pyvenv.cfg: A configuration file specifying details about the environment.
Activation Scripts: (activate, activate.fish, Activate.ps1, activate.bat) These are the scripts inside .venv/bin (or .venv/Scripts) that you source or run to activate the environment. You don’t typically edit these.
requirements.txt (Common Practice): A text file where you list the packages your project needs, often with specific versions (e.g., requests==2.28.1). You create and manage this file. uv pip freeze generates it, and uv pip install -r / uv pip sync uses it.
pyproject.toml (Modern Standard): The modern standard for Python project configuration, including dependencies. If you use this, uv pip install . will install dependencies specified within it.

Typical Workflow Summary

cd my_project
uv venv .venv (Only needs to be done once per project)
source .venv/bin/activate (Do this every time you start working in a new terminal)
uv pip install requests (Install new packages as needed)
uv pip freeze > requirements.txt (Update requirements file after installing/updating)
- Alternatively, manually edit requirements.txt or pyproject.toml and then run uv pip install -r requirements.txt or uv pip sync requirements.txt or uv pip install .
Work on your project code…
deactivate (When you’re done)

Remember to add .venv to your .gitignore file to prevent committing the entire virtual environment to version control. Only commit your source code and dependency definition files (requirements.txt or pyproject.toml).