Import Python Project Tutorial with UV
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.
the brief, no-explanation-needed version:
Import an existing Python project. Common options:
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/.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].
In standalone terminal, navigate to your imported project folder using
cd folder/to/project.Install package dependencies
- If the project has a
uv.lockpage (which indicates it is a uv project with its dependencies stored in this file):- In the terminal (make sure the current working directory is your project folder), run:
uv sync.
- In the terminal (make sure the current working directory is your project folder), run:
- If the project has a
requirements.txtfile instead:- run
uv syncand thenuv add -r requirements.txt.
- run
- Otherwise, install each needed package independently using
uv add [package_name].
- If the project has a
Open VSC Code and configure:
- File –> Open Folder –> select project folder
- Select Python Interpreter:
- Open Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS)
- Type “Python: Select Interpreter”
- Choose the interpreter from .venv (it should show up as ./venv/bin/python or similar)
- when you first open or create a new Jupyter notebook (
.ipynb) you may be prompted to choose an interpreter, choose the same.venvPython interpreter.
Verify Set up: run
uv python --versionanduv pip listto 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.
open the chosen GitHub repository. In this tutorial, we will import the repository for Dartmouth Libraries’ Python Essential Workshop Series.
Click the green “Code” button on the repository page
Select “Download ZIP”
Extract the ZIP file to a memorable location (e.g.,
~/Documents/Python-Courses/)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.
- open the chosen GitHub repository.
- Click the green “Code” button on the repository page
- 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)
- 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
- To update the local version of the repository after the online version has been updated:
git pull origin main
- If you have permissions to edit the online repository you can use
git add,git commit, andgit pushto 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
- Navigate to your new project folder within a standalone terminal using the
cdcommand:
cd path/to/[repository-name]
- Tips
- to navigate to an absolute path:
cd C:/Users/myusername/Documents/python-projects/imported-project - to navigate up one directory:
cd ..or up three:cd ../../.. - to navigate down one directory:
cd subfolder-nameor threecd subfolder1/subfolder2/subfolder3.
- to navigate to an absolute path:
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.tomlCreates/updates
uv.lockfor 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:
- 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
- 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
Launch VS Code
File → Open Folder
Select the course repository folder
Step 2: Select Python Interpreter
Open Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS)
Type “Python: Select Interpreter”
Choose the interpreter from
.venv(it should show up as./venv/bin/pythonor 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:
VS Code will prompt you to select a kernel
Choose the same
.venvPython 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:
- Install Visual Studio Build Tools
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:
Make sure
.venvfolder exists in your project rootReload VS Code (Ctrl+Shift+P → “Developer: Reload Window”)
Manually browse to the interpreter:
- Windows: `.venv\Scripts\python.exe`
- Mac/Linux: `.venv/bin/python`
Issue: Jupyter notebooks won’t run
Solution:
Ensure Jupyter extension is installed
Install ipykernel in your environment:
uv pip install ipykernel
Select the
.venvkernel when opening a notebookRestart VS Code if needed
Issue: “Import could not be resolved” warnings in VS Code
Solution:
Ensure you’ve selected the correct Python interpreter
Check that
python.analysis.extraPathsincludes your project rootReload VS Code window
Issue: Cannot write to .venv directory (permission errors)
Solution:
Don’t use
sudowith uv commandsEnsure 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
.venvfolderUse
uv sync --offlineif 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.py2024_01_15_sales_report.csvfigure_01_scatterplot.png
Bad:
script1.pyfinal FINAL (2) copy.pysales data.csv(spaces can be problematic)
Running Python Code
In Terminal:
# Always use uv run to ensure correct environment
uv run python scripts