Import Python Project Tutorial with UV

Author
Affiliation

Jeremy Mikecz

Research Facilitation, Dartmouth Libraries

Published

January 13, 2026

Importing an existing Python Project with VSC and UV

This document provides detailed instructions for setting up your Python environment for this course/workshop. You should have already read the information in the 00_setup_slides and completed the installation of Visual Studio Code and Python using uv by following Setup Notebook 01.

These coding notebooks and other materials are stored in the python-setup repository in Dartmouth Libraries Github.

TipBrief Cheatsheet

the brief, no-explanation-needed version:

  1. Import an existing Python project. Common options:

    1. most users: Download static copy from Github: Code –> Download Zip –> unzip –> move into a logical place on our hard drive or cloud server, i.e. ~/Documents/python_projects/.

    2. advanced users: Copy dynamic “clone” from Github: Code –> Copy the SSH or HTTPs url –> open a standalone terminal (outside of VSC), navigate to the root directory where you want to place this project, and run git clone [REPO-URL].

  2. In standalone terminal, navigate to your imported project folder using cd folder/to/project.

  3. Install package dependencies

    1. If the project has a uv.lock page (which indicates it is a uv project with its dependencies stored in this file):
      1. In the terminal (make sure the current working directory is your project folder), run: uv sync.
    2. If the project has a requirements.txt file instead:
      1. run uv sync and then uv add -r requirements.txt.
    3. Otherwise, install each needed package independently using uv add [package_name].
  4. Open VSC Code and configure:

    1. File –> Open Folder –> select project folder
    2. Select Python Interpreter:
      1. Open Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS)
      2. Type “Python: Select Interpreter”
      3. Choose the interpreter from .venv (it should show up as ./venv/bin/python or similar)
      4. when you first open or create a new Jupyter notebook (.ipynb) you may be prompted to choose an interpreter, choose the same .venv Python interpreter.
  5. Verify Set up: run uv python --version and uv pip list to see Python version and packages installed to the project environment


More detailed instructions and explanations:

Downloading a Project Repository from Github

Option 1: Download as ZIP

This method is recommended for newer programmers not yet familiar with git and Github and for any user who only needs a static copy of the repository.

  1. open the chosen GitHub repository. In this tutorial, we will import the repository for Dartmouth Libraries’ Python Essential Workshop Series.

  2. Click the green “Code” button on the repository page

  3. Select “Download ZIP”

  4. Extract the ZIP file to a memorable location (e.g., ~/Documents/Python-Courses/)

  5. Important: To get updates, you’ll need to re-download

Option 2: Using Git (Advanced)

This method is recommended for users who:

  • are familiar with git and Github

  • have git installed

  • have set up a Github account

  • wish to create a dynamic copy (“clone”) of the repository.

A clone allows you to update your local repo when its online counterpart as been updated (using the pull command in git). It also allows you to push any changes you made locally back up to the remote repository, but only if the repository administrator has given you these privileges.

  1. open the chosen GitHub repository.
  2. Click the green “Code” button on the repository page
  3. Under Clone copy the HTTPS or SSH url (recommended option: set up an SSH Key with your Github account and use SSH; if you don’t have such a key then you will need to use HTTPS)
  4. Open a standalone terminal (outside VSC). Navigate to the root directory where you want to store this project. Run the following:
# before cloning, move the current working directory to the folder where you want to clone this project
#paste the https or ssh repo url below and run:
git clone in VSC project
# for example:
# git clone git@github.com:Dartmouth-Libraries/py-essentials_ws.git
  1. To update the local version of the repository after the online version has been updated:
git pull origin main
  1. If you have permissions to edit the online repository you can use git add, git commit, and git push to push your local changes back to the online repo. This is for more advanced users and is outside the scope of this tutorial.

Setting Up the Python Environment

Step 1: Open Project in VSC

  1. Navigate to your new project folder within a standalone terminal using the cd command:
cd path/to/[repository-name]
  1. Tips
    1. to navigate to an absolute path: cd C:/Users/myusername/Documents/python-projects/imported-project
    2. to navigate up one directory: cd .. or up three: cd ../../..
    3. to navigate down one directory: cd subfolder-name or three cd subfolder1/subfolder2/subfolder3.

Step 2: Create Virtual Environment and Install Dependencies

2a. If the Imported Project is a uv project

You can tell if a repository is set up for uv if it has a uv.lock file in its root folder.

Run the following in the terminal:

# This creates a .venv directory and installs all packages
uv sync

This command:

  • Creates a virtual environment in .venv/

  • Installs Python if the correct version isn’t available

  • Installs all packages specified in pyproject.toml

  • Creates/updates uv.lock for reproducibility

2b. If the Imported Project has a requirements.txt file

Prior to uv, Python project dependencies were usually stored in a requirements.txt file. To install all dependencies from this file and convert the project to a uv project, run the following in the terminal:

  1. First, initiate uv for this project:
uv sync
uv add -r requirements.txt

If this doesn’t provide desired results, review the documentation on this process in the uv guide.

2c. If the Imported Project has no dependencies list

  1. As you encounter packages needed to run code in this project, you can install them one at a time or multiple at a time like this: uv add package1 package2 package3.

Configuring Visual Studio Code

Step 1: Open the Project

  1. Launch VS Code

  2. File → Open Folder

  3. Select the course repository folder

Step 2: Select Python Interpreter

  1. Open Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS)

  2. Type “Python: Select Interpreter”

  3. Choose the interpreter from .venv (it should show up as ./venv/bin/python or similar)

If the .venv interpreter doesn’t appear:

  • Click “Enter interpreter path…”

  • Navigate to: .venv/Scripts/python.exe (Windows) or .venv/bin/python (Mac/Linux)

Step 3: Configure Jupyter

When you open a .ipynb file:

  1. VS Code will prompt you to select a kernel

  2. Choose the same .venv Python interpreter

Verifying Your Setup

Manual Verification

To test your set up:

# Check Python version
uv run python --version      # should be the Python version assigned to your local environment

# Test package imports
uv run python -c "import pandas; import numpy; import matplotlib; print('All packages loaded successfully!')"

# List installed packages
uv pip list                  # should just list packages imported into this project's environment

Troubleshooting

Issue: uv: command not found

Solution: The installation directory isn’t in your PATH.

Windows:
Add %USERPROFILE%\.cargo\bin to your PATH environment variable.

macOS/Linux:
Add this to your ~/.bashrc, ~/.zshrc, or equivalent:

export PATH="$HOME/.cargo/bin:$PATH"

Then run: source ~/.bashrc (or ~/.zshrc)

Issue: “Python version X.Y required but X.Z found”

Solution: uv can install Python for you:

uv python install 3.11
uv sync

Issue: Package installation fails with compilation errors

Solution 1: Ensure you have build tools installed

Windows:

macOS:

xcode-select --install

Linux (Ubuntu/Debian):

sudo apt-get install build-essential python3-dev

Solution 2: Try installing pre-built wheels:

uv pip install --only-binary :all: [package-name]

Issue: VS Code doesn’t recognize the .venv interpreter

Solution:

  1. Make sure .venv folder exists in your project root

  2. Reload VS Code (Ctrl+Shift+P → “Developer: Reload Window”)

  3. Manually browse to the interpreter:

-   Windows: `.venv\Scripts\python.exe`

-   Mac/Linux: `.venv/bin/python`

Issue: Jupyter notebooks won’t run

Solution:

  1. Ensure Jupyter extension is installed

  2. Install ipykernel in your environment:

uv pip install ipykernel
  1. Select the .venv kernel when opening a notebook

  2. Restart VS Code if needed

Issue: “Import could not be resolved” warnings in VS Code

Solution:

  1. Ensure you’ve selected the correct Python interpreter

  2. Check that python.analysis.extraPaths includes your project root

  3. Reload VS Code window

Issue: Cannot write to .venv directory (permission errors)

Solution:

  • Don’t use sudo with uv commands

  • Ensure you have write permissions to the project directory

  • On Windows, run terminal as regular user (not administrator)

Issue: uv sync is very slow

Possible causes:

  • First run always takes longer

  • Slow internet connection

  • Antivirus scanning

Solutions:

  • Be patient on first run

  • Disable antivirus temporarily for .venv folder

  • Use uv sync --offline if you’ve run it before

Best Practices for This Course

File Organization

  • Keep all work within this project folder

  • Use relative paths (or pathlib)

  • Save scripts with descriptive names: verb_noun.py (e.g., analyze_sales.py)

Naming Conventions

Good:

  • clean_data.py

  • 2024_01_15_sales_report.csv

  • figure_01_scatterplot.png

Bad:

  • script1.py

  • final FINAL (2) copy.py

  • sales data.csv (spaces can be problematic)

Running Python Code

In Terminal:

# Always use uv run to ensure correct environment
uv run python scripts