Skip to content

Python project quick start

This guide will help you create your first Python project. If you haven't installed Python yet, start with the installation guide.

Prerequisites

Before starting, make sure you have:

Choose your project location

Do not create projects in cloud storage

Creating Python projects in cloud-synced folders (OneDrive, iCloud, Dropbox) often causes issues. File locking and syncing can corrupt the environment.

Store projects in: ~/projects/ or C:\Users\<user>\projects\ instead.

Create your project in a location that's not synced to cloud storage. A good location is:

cd ~\projects
mkdir myproject
cd myproject

Create your project in a location that's not synced to cloud storage. A good location is:

mkdir -p ~/projects/myproject
cd ~/projects/myproject

Create your project in a location that's not synced to cloud storage. A good location is:

mkdir -p ~/projects/myproject
cd ~/projects/myproject

Initialize your project

Initialize your project with uv:

uv init

This creates:

  • pyproject.toml - Project configuration and dependencies
  • main.py - Starter Python script
  • .python-version - Specifies the Python version for this project
  • .venv/ - Virtual environment (created automatically when needed)
  • uv.lock - Lock file ensuring reproducible installations (created when adding packages)

Add packages

Add the packages you need to your project, e.g numpy, scipy, matplotlib, and sund for a typical ODE based modelling project:

uv add numpy scipy matplotlib sund

This automatically:

  • Installs the packages in your virtual environment
  • Updates pyproject.toml with the dependencies
  • Creates/updates uv.lock to ensure reproducible installations

Write your code

Open VS Code/Codium and navigate to your project folder. Edit main.py (or create new Python files) with your code. For example:

import matplotlib.pyplot as plt
import numpy as np
import sund

# Your code here
print("Hello from my Python project!")

Run your code

Run your Python script, either in the terminal or using the integrated terminal in your editor:

uv run main.py
uv run vs python

With uv, you use uv run instead of the traditional python command. This automatically activates your virtual environment and ensures all dependencies are installed before running your script. You can also activate the environment manually and use python if you prefer - see the environments guide.

That's it! uv automatically:

  • Activates the virtual environment
  • Ensures all dependencies are installed
  • Runs your script

Running with the built-in runner/debugger

VS Code/Codium has built-in support for running and debugging Python code. You can use the "Run" and "Debug" buttons in the editor, which will automatically use the correct Python environment for your project (once selected). This allows you to set breakpoints, inspect variables, and step through your code interactively. Before you do this, be sure to select the correct environment in the bottom left corner of VS Code/Codium (it should show the name of your project and the Python version if you have a Python file open). Now, you can run your code with the built-in runner or start a debugging session to troubleshoot and understand your code better (play icon in the top right corner when a Python file is opened).

Working with an existing project

If someone shares a project with you (containing pyproject.toml):

cd existing-project
uv sync  # Installs all dependencies automatically
uv run main.py