I’ve been using uv to manage my Python environments. It’s a great tool, but I recently encountered an issue with the VIRTUAL_ENV environment variable.

The Problem

The issue arose when I was using uv to remove a package from what I thought was my activated virtual environment:

(cbsim) ➜  cbsim git:(km/mle-1722/evaluation-harness) ✗ uv remove papermill
warning: `VIRTUAL_ENV=/Users/khalil/Desktop/cbsim/.venv` does not match the project environment path `.venv` and will be ignored

The error message revealed the root cause: my VIRTUAL_ENV environment variable was pointing to an absolute path that didn’t match uv’s expected relative path.

The Solution

I located the issue in my virtual environment’s activation script (cbsim/.venv/bin/activate) where the VIRTUAL_ENV variable was incorrectly set to:

VIRTUAL_ENV="/path/to/unexpected/cbsim/.venv"

I updated it to the correct relative path:

VIRTUAL_ENV="/path/to/expected/cbsim/.venv"

After reactivating the virtual environment, uv commands worked as expected.

Prevention

This mismatch likely occurred because the virtual environment was created or moved after initial setup. To avoid this issue:

  • Always create virtual environments in your project root
  • Recreate the virtual environment if you move your project directory