官网: https://docs.astral.sh/uv/

venv 虚拟环境创建

方法 1：直接通过路径创建

# 也可以用软链接
uv venv --python /usr/bin/python

方法 2：使用版本号（由 uv 自动匹配系统版本）

可以直接指定版本号，uv 会优先尝试查找已安装的版本

uv venv --python 3.11.6

方法 3：在项目中固定此版本

# 在项目根目录执行
uv python pin /usr/bin/python

# 然后创建环境，它会自动使用固定的版本
uv venv

常见问题

防止 pyproject.toml 对 uv run 造成影响

uv run --no-project xxx.py
# or
uv run --no-sync xxx.py

• –no-project, --no_workspace
  Avoid discovering the project or workspace.
  Instead of searching for projects in the current directory and parent directories, run in an isolated, ephemeral environment populated by the --with requirements.
  If a virtual environment is active or found in a current or parent directory, it will be used as if there was no project or workspace.
• –no-sync
  Avoid syncing the virtual environment [env: UV_NO_SYNC=]
  Implies --frozen, as the project dependencies will be ignored (i.e., the lockfile will not be updated, since the environment will not be synced regardless).

pyproject.toml

uv.lock 哈希值不匹配

常见引用本地 whl 库, 重新构建后造成

• 文件定义

  [tool.uv.sources]
  sfl = { git = "https://github.com/xxx", rev = "7de8a36e57ff42aa37ba8343897e45ee1de458b4" }
  spu = [ 
  	{ path = "/path_to_py_whl_version1.whl", marker = "python_version == '3.10'" }, 
  	{ path = "/path_to_py_whl_versionw.whl", marker = "python_version == '3.11'" },
  ] 
  

• 解决方案如下

  uv lock --upgrade-package package_name
  
  # or 清理缓存后重新同步
  uv cache clean package_name
  uv sync
  
  # or
  uv sync --reinstall
  

开发/预发布版本包的安装

• 问题: but pre-releases weren’t enabled (try: --prerelease=allow)
• 解决:

  uv sync --prerelease=allow
  # 或者更新 lock 文件
  uv lock --prerelease=allow
  # or
  uv pip install xxx.whl --force-reinstall --prerelease=allow
  # or
  uv cache clean package_name
  # or
  uv sync --reinstall-package package_name --prerelease=allow
  

可编辑模式安装

uv pip install -e . --force-reinstall --no-cache