See also: Why you should avoid clicking buttons

Troubleshooting your Python Environment

Environments vs. Directories (Folders)

Directories are paths on your file system. They contain files or other directories. Think of directories as locations. Environments are sets of configuration variables and their values, plus third-party libraries. Think of environments as configuration or sets of tools.

People sometimes get confused, because environments are often stored as directories. Even more confusingly, experienced developers will use the same language to describe being “in an environment” and “in a directory”.

Translation

Phrase	Explanation
Are you in the right environment?	Refers to using a specific configuration of libraries and settings for a project. Translates to “Have you selected the appropriate environment using a command like conda activate or source .venv/bin/activate?”
Are you in the right directory?	Refers to being in a specific folder on your file system that contains files. Translates to “Have you navigated to the appropriate directory using a command like cd?”

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.

Here’s an example (styled like the output of the tree command).

myproject/              # This is the top-level project directory
├── .venv               # This is the directory that contains the Python environment
│   ├── bin             # Contains executable files like Python and pip
│   ├── include         # Contains C headers from the Python packages
│   ├── lib             # Contains the installed packages and their dependencies
│   └── pyvenv.cfg      # Configuration file for the virtual environment
├── project.py          # Main application file
└── requirements.txt    # File listing the dependencies for the project

In this example, the .venv directory is used to separate the environment from the main project files, ensuring that the project dependencies do not interfere with the global Python installation.

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:

# cd to the containing folder for .venv, then...
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

1. 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:

1. From the terminal:

   which python
   

2. From inside Python:

   import os
   os.system("which python")
   

Check what packages you have installed:

1. 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'
   

Change the Python version that VSCode is using:

There are at least two uses for Python in VSCode:

• Running scripts
• Linting & Formatting

Look for the bottom-most bar in the VSCode UI, look towards the bottom right corner. If you have the Python extension installed, you should see some Python version indicated.

_