Virtual Environments#
This guide covers managing python environments with UV and conda.
TLDR
If you know conda, use conda.
Otherwise, install and learn about uv and substitute pip install <PACKAGE> with uv pip install <PACKAGE> for a drop-in pip replacement.
Action |
UV |
Conda |
|---|---|---|
Create environment |
|
|
Activate |
|
|
Install package |
|
|
Add/remove package |
|
(edit |
Sync with pyproject.toml |
|
✖️ Not supported |
Upgrade packages |
|
|
Managing environments: UV#
uv is a complete drop-in replacement for pip.
If you know pip, you already know uv.
You just prefix commands:
pip install . # old
uv pip install . # new
Using uv has a key advantage: packages are cached globally, so you can quickly recreate them without worrying about contaminating your base environment.
Tip
With UV, re-creating your environment is much faster than with conda thanks to it’s dependency caching.
This makes deleting your environment an appropriate solution if you run into environemnt conflicts.
Create an environment#
By default, uv venv will create a folder .venv which is used as your environemnt.
This folder will be placed in your current working directory:
USER@SERVER ~/repos/mypackage
$ uv venv
Using CPython 3.11.12
Creating virtual environment at: .venv
You can specify a name for the environment:
USER@SERVER ~/repos/mypackage
$ uv venv myenv
Using CPython 3.11.12
Creating virtual environment at: myenv
You can also indicate which python to use:
USER@SERVER ~/repos/mypackage
$ uv venv myenv --python=39 # or 310, 311, 312, 313
Using CPython 3.9.22
Creating virtual environment at: myenv
Warning
uv venv will create a folder in your current directory named .venv, which is a python standard and will be automatically chosen by many development environments e.g. VSCode.
To distinguish between environments, name the environment by substituting
Some IDE’s may struggle to locate named environments (e.g. some versions of Pycharm).
Activate the environment (optional, good practice)#
If you named your environment, replace .venv below with the name of your environment:
source .venv/bin/activate
source .venv/Scripts/activate
If you don’t activate the environment, but you are running code from a directory that has a .venv folder, it will still be used automatically in most cases.
Install python packages#
uv pip install <PACKAGE>
This works just like pip.
You can install packages from the filesystem just as you can with pip:
uv pip install .
Or use higher-level uv features like sync:
uv sync --all-extras
The --all-extras get’s all extra dependencies, like [notebook, gui], if the repository has any.
Command |
Description |
|---|---|
|
Create an env, optionally name it myenv (not recommended) |
|
Update your environment based on the current most up to date packages |
|
Add/remove packages (updates |
|
Upgrade single/all packages |
Managing environments: conda#
Create an environment#
For more ways to create an environment (such as from a environment.yml file), see Creating an Environment with Commands.
conda create -n myenv -c conda-forge python=3.xx
Activate the environment#
Warning
Don’t forget to activate your environment!
If you do, it will be installed in the base conda environment.
Unlike uv,
which will look for a folder in your current directory,
conda will default to installing packages into the base environment which is shared across all user environments and often leads to package conflicts.
The only fix is to reinstall conda.
conda activate myenv
Install python packages#
For details about installing python packages with conda, see conda docs on Managing Packages.
conda install <package1> <package2>
Virtual environment options#
You could learn the in’s and out’s for all of the virtual environments below. Don’t do this (use UV, the community is finally settling on a standard).
There are generally three camps:
Tools that handle only Python packages (venv, pyenv)
Tools that handle python packages AND system dependencies like ffmpeg, opencv, cuda (mamba, conda)
Tools built on top of the above to make them easier to use, faster, etc. (UV, pixi, which uses UV under the hood).
conda, miniconda, miniforge, anaconda, mamba, micromamba, pixi
pip, pip-tools, pipx, venv / pyvenv, virtualenv, pipenv, poetry, twine, hatch, asdf, uv
Why not conda?#
pip(and UV) can build most system packages you need from source.Most Python libraries now ship prebuilt wheels (binaries).
The main selling point for
conda(handling system binaries) is much less relevant today.The
condamaintainers have moved toward venv-based setups (pixi and uv).
If you must use conda, only use miniforge3.
Many recommended setup steps for miniconda/anaconda are mimicking the defaults of miniforge3.
If you already know conda, that’s fine — just avoid mixing pip install and conda install after your initial setup unless you have to.
Mixing conda and uv#
uv will automatically fallback to using a conda environment if no .venv folder is found:
USER at pop-os in ~/repos/work/mbo_utilities (master●)
$ uv pip list | grep imgui
Using Python 3.12.6 environment at: /home/USER/miniforge3
imgui-bundle 1.6.2
So even if you’re using conda, uv will work all the same.
We recommend turning off automatic environment activation for conda in this case:
conda config --set auto_activate_base false
You can still call conda activate myenv, but only if conda is called explicitly.
Debugging environments#
Most bugs and frustration in Python come from mismanaging virtual environments.
No matter what command you’re running, check the terminal outputs for a filepath that points to python.
For jupyterlab:
