Getting a Python Project Running: Virtual Environments, Packages and Common Errors

Getting a Python project to run can involve more than opening a file and pressing the Run button.

While setting up my career pathway project, I encountered a project folder nested inside another folder with the same name. When running one of its scripts, I also encountered this error:

ModuleNotFoundError: No module named 'matplotlib'

These are useful examples of why the setup deserves attention. Before investigating the application itself, it helps to establish which folder, Python installation and packages are being used.

This walkthrough uses Windows and VS Code, with Microsoft's Python extension installed. It assumes an existing project that uses a requirements.txt file. Start with the project's README: its supported Python version, installation instructions and launch command take priority.

1. Open the actual project folder

An extracted download can contain an outer folder and an inner project folder. Open the folder containing the project's source code and setup instructions through File → Open Folder in VS Code.

Then open Terminal → New Terminal and list the contents:

dir

For this walkthrough, you should be able to see requirements.txt. If it is inside another folder, open that folder or change into it before continuing.

The terminal's working directory matters. A command using a relative filename looks for that file relative to the current directory.

2. Check which Python version is available

Run:

python --version

Compare the result with the version supported by the project. If Windows cannot find python, try:

py --version

If py works, you can use it to create the environment in the next step. If neither command works, resolve the Python installation first. The Python Packaging User Guide (opens in a new tab) covers the installation prerequisites.

3. Create and activate a virtual environment

A virtual environment gives a project its own Python environment and installed packages. Keeping dependencies separate helps when different projects need different package versions.

From the project folder, create one:

python -m venv .venv

If you are using the Windows py command, use py -m venv .venv instead.

Activate it with the command for your terminal:

The prompt usually gains a (.venv) prefix. To see which Python executable the terminal is using, run:

python -c "import sys; print(sys.executable)"

Its path should point to your project's .venv folder. Python's virtual environment documentation (opens in a new tab) explains creation and activation.

4. Install the project's packages

A dependency is a package the project needs. For a project with requirements.txt, run:

python -m pip install -r requirements.txt

Here, pip installs packages, and -r tells it to read the requirements file. Using python -m pip ties the installer to the Python interpreter invoked by that command. This is helpful when several Python installations exist on one computer.

Let installation finish successfully before launching the application. If the README specifies an additional requirements file for research or development, follow those instructions too. See the pip user guide (opens in a new tab) for requirements-file installation.

5. Select the same environment in VS Code

Your editor should use the same environment as your terminal.

Press Ctrl + Shift + P, run Python: Select Interpreter, and choose the interpreter inside your project's .venv folder.

Open a new terminal and verify the interpreter path again. Existing terminals can retain their earlier environment, so check instead of relying only on the editor's selection. The VS Code environment guide (opens in a new tab) explains how interpreter selection affects running and debugging code.

6. Use the project's launch command

Different projects start in different ways. For an ordinary script named main.py, the command could be:

python main.py

For a Streamlit application named app.py, use:

python -m streamlit run app.py

Replace these example filenames with the actual entry point from the README. A file used for model training or experiments may not launch the user interface.

The Streamlit command starts a local server and opens the application in a browser. Keep its terminal running while using the app. This launch method is documented in Streamlit's run guide (opens in a new tab).

Common errors and what to check

For the Matplotlib example, check its installation with:

python -m pip show matplotlib

If it is missing, first follow the project's dependency instructions. For a project that requires Matplotlib without specifying a version, a direct installation is:

python -m pip install matplotlib

The pip guide (opens in a new tab) documents both installation and package inspection. For other missing modules, check the documented package name; an import name and an installation name can differ.

If PowerShell blocks Activate.ps1, you can invoke the environment's Python directly:

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Use that interpreter path for subsequent Python commands too. Activation is a convenience; Python's documentation (opens in a new tab) confirms that an environment can be used without it.

The routine I want to make automatic is simple: check the folder, check the interpreter, install the documented dependencies, then use the documented launch command. Those checks give me a clearer starting point when something fails.