Troubleshooting your Python Environment

Environments vs. Directories (Folders)

Directories are locations on your file system. Environments are sets of configuration variables and their values.

Environments are often stored as directories. This sometimes leads people to confuse the two. Sometimes the appropriate environment for your project is stored in the project directory. Some ways of making environments store environments in a completely different directory.

What does an environment do?

A python environment dictates:

The path to the Python interpreter (the program that reads Python files and turns them into commands your computer understands).
The third-party packages that are available to the Python interpreter.
Often, the path to pip

Ways to troubleshoot your environment

You might encounter difficulty importing third-party packages (e.g. ModuleNotFoundError when trying to import pandas). This usually means you are trying to run your code with the wrong Python environment active.

You need to check:

What environment is the package installed in?
What environment are you trying to use it in?

The answers to these questions should be the same environment. If they are different, you need to reconcile this by:

Changing the environment you’re using to one where the package is installed, or…
Keeping the environment the same, and installing the package there

Make sure you have activated the environment you want to use

Using conda as your environment manager:

conda activate environment-name

Using uv as your environment manager:

source .venv/bin/activate

Note that conda stores environments in one central location. This means you can activate the environment from any location in the terminal. Uv stores environments in whatever folder you are in when you do uv venv. You must be in the same folder when you do source .venv/bin/activate.

See “check the path to the Python interpreter” for tips on how to make sure this step succeeded.

Check that only one environment manager is active

I sometimes recommend using Miniconda to install Python and uv to manage packages thereafter. This combo works fine, but the Miniconda installer can enable conda to activate itself whenever you open a shell. This leads to problems if you also activate an environment using `source .venv/bin/activate`, the standard approach if you are using uv. This is easy to fix.

Check if conda is active:
```
echo $CONDA_PREFIX
which python
```
If conda is active:
```
conda deactivate
which python
```

Check the path to the python interpreter:

From the terminal:
```
which python
```
From inside Python:
```
import os
os.system("which python")
```

Check what packages you have installed:

From the terminal:

Check the path to pip

which pip

then

pip freeze

If you’re looking for a specific package:

pip freeze | grep 'package-name'

If you’re using uv

uv pip freeze
uv pip freeze | grep 'package-name'

📚 gabe's wiki

Explorer

troubleshooting_python_env