If you’re new to Python, then you’ll want to start here. If you’re already comfortable using Python, then feel free to dive straight into the AoC walkthroughs, using the links above.
Why Python?
If you’re a newbie to programming, then Python is a great language to start with. If you have a lot of programming experience, then guess what? Python is an amazing language to learn, and you’ll love it.
Many years ago, I used to write software for a living. Back then, my preferred languages were Java and C#. These days, I don’t write code in my job, though I do still need to know my way around. Now I write code as a hobby. But I can honestly say: of all the programming languages I’ve ever used, Python is my favourite.
For those of you coming from a background with languages like C, C#, Java, JavaScript… You may find Python’s syntax and structure a bit jarring. But trust me: once you get your head around the differences, you’ll love it, just like I do.
Here are some of Python’s strengths:
- It’s extremely readable. Its syntax tends to be aligned to natural language.
- It’s highly portable. Your Python programs will run on just about any operating system.
- It’s really easy to install and use.
- It’s open source: free to use, and free to distribute.
- It’s extremely versatile. You can use it for console applications, web applications, automation, APIs, data science, machine learning, maths and statistics, graphs, visualisation, writing games, and so much more.
- There are a massive number of open source libraries available, to do just about any task.
My Recommendations for Getting Started
I recommend working through the following, to get started:
- Install Python 3.13+
- Get a development environment / editor
- Get Git
- Learn the Python basics
- Environments & Packages with uv (replaces manual
venvandpip) - Explore the Repository CLI
Getting and Installing Python
To execute Python programs, you need a recent Python runtime installed (Python 3.13+ is recommended for this repository). To check what you have installed, open your terminal and run:
python --version
If you get a response that shows you have Python 3.13+ installed, then you’re good to go. (Alternatively, uv can download and manage isolated Python versions for you automatically!) E.g.

If you haven’t got Python installed, download the latest Python 3.13+ release from python.org, or install it via uv python install 3.13. Take a look here if you need additional guidance.
Development Environment / Editor
You can write and run Python programs without a development environment. But it’s a much better — and more effective — experience, if you have one.
A development environment adds a wealth of features, such as:
- The ability to conveniently organise files and folders into projects.
- Syntax colouring.
- Linting — flagging of problems in your code, such as syntax errors, warnings, stylistic errors, or something potentially dangerous.
- Autocompletion — the ability to offer likely completion of what you’re typing.
- Refactoring — the ability to rename symbols, extract methods, etc.
- Debugging — the ability to step through code, show the current value of variables, stop at break points, etc.
- Keyboard commands and shortcuts that greatly improve productivity.
- Integration with terminals / consoles / shells.
- The ability to install a number of freely available extensions and plugins, e.g. to integrate Git, Docker, Jupyter Notebooks, enhanced visualisation of certain file types and formats, and so on.
Visual Studio Code
My favourite development environment is Visual Studio Code — aka VS Code — which can be downloaded and installed from here. (Note: VS Code is not the same as Visual Studio, which is a different product.)
Some benefits of VS Code:
- It is open source and free.
- It is platform-agnostic. I.e. you can run it on a wide variety of operating systems, including Windows, Linux, and macOS.
- Unlike some development environments, VS Code is a very lightweight and fast editor.
- It is language-agnostic. You can use it write much more than just Python. E.g. if you want to write HTML, JavaScript, Markdown, YAML… No problem!
- It is supported by a massive library of free extensions and plugins.
- Really swish Git integration, out of the box.
- It looks great.
- It is highly configurable.

Installing and Setting Up VS Code
Check out the following useful links:
- Obtaining and Installing VS Code
- VS Code Documentation Pages
- VS Code Getting Started Videos
- Setting Up VS Code
- Python in VS Code
- Getting started with Python in VS Code Tutorial
Install Useful Extensions
Now you’ll want to install some extensions that will make your Python — and general development — experience better. In VS Code, click on the Extensions button in the left hand panel of buttons. I’d recommend installing the following:
- Python (Microsoft) — provides rich support for the Python language, including features such as IntelliSense (provided through Pylance), linting, debugging, code navigation, code formatting, refactoring, variable explorer, test explorer, and more. Note that when you install this extension, it automatically installs Pylance and Jupyter (for Jupyter Notebook support).
- Better Comments — a cool plugin that enhances your comments.
- Git Graph — for visualising your Git repos.
- Jupyter — for running Jupyter notebooks inside of VS Code.
- Python Docstring Generator — a cool plugin that helps with the creation of docstrings. If you don’t know what these are, then don’t worry about this just yet!
- Rainbow CSV — colourises any CSV files you open in VS Code.
- Reload — adds a button to reload your VS Code environment.
- Python Indent — auto-indentation for Python.
Note: if you’ve followed the Getting started with Python in VS Code Tutorial, this will have guided you through installing some of these extensions.
Git
Git is an extremely popular version control system (VCS). A VCS provides capabilities like these:
- The ability to store and track all the changes to your code or project.
- The ability to revert your project to any point in its history. E.g. to get your code back to a previous state, before you made some catastrophic error!
- The ability to share and collaborate with others.
- The ability to obtain code from others.
- The ability to branch code, e.g. for experimenting, building new features, fixing bugs, etc.
- The ability to integrate with other tools, like bug tracking and CI/CD pipelines.
So Why Git?
Git is an open source VCS, created by the legendary Linus Torvalds. You know… The guy that created Linux.
Git is:
- Really easy to use.
- Platform-agnostic.
- Extremely fast.
- Distributed! This means that you always have a complete copy of a project’s history on your own machine! But you can (and should) make use of a centralised, cloud-based repo service, like GitHub. In fact, all of my AoC source code is stored on GitHub, which is how I make it available to you.
Installing Git
- Download and install git.
- See the Git Getting Started documentation.
- Git Installation Guide
- Git Initial Setup
Python Basics
Finally, if you’re completely new to Python, you might want to learn some basics before you begin with AoC. Here’s a list of some decent learning material to help you get started:
- The Python Handbook
- The Official Python Tutorial
- The w3schools Python Tutorial
- Google’s Python Class
Using uv (Recommended)
In this repository, uv completely replaces manual python -m venv creation and manual pip install commands. Powered by pyproject.toml and uv.lock, uv manages the Python 3.13+ runtime, virtual environment (.venv/), and all dependencies deterministically:
# Hydrate the complete development environment in one step:
uv sync --dev --extra jupyter --extra legacy # or simply: make install
[!NOTE]
make installinstalls core dependencies, dev tools, JupyterLab, andlegacyextras (dazbo-commonsandcolorama) so that historical solutions from 2015–2024 remain runnable locally alongside modern Template v3 code.
Once installed, commands prefixed with uv run execute inside .venv/ automatically — without needing manual activation scripts (source .venv/bin/activate):
# Run any script inside .venv/
uv run python src/AoC_2025/d01/d01.py
# Launch JupyterLab for interactive notebooks
uv run jupyter lab
VS Code will automatically detect .venv/ as the default Python interpreter once created.
Repository Workflow and CLI Showcase
The repository includes a dedicated CLI (uv run aoc) that streamlines everyday Advent of Code workflows:
# 1. Inspect puzzle progress and completion across years (with clickable hyperlinks):
uv run aoc list
uv run aoc list 2025
# 2. Fetch puzzle descriptions and sample inputs without touching a browser:
uv run aoc fetch 2025 1 --write-sample
# 3. Run solutions against sample assertions or real inputs:
uv run aoc run 2025d01 -s # Validate sample assertions with debug logging
uv run aoc run 2025 1 # Run against real input.txt
# 4. Scaffold an entire new Advent of Code year using Template v3:
uv run aoc new-year 2026 # Defaults to 12 days for 2025+
# 5. Run the offline verification gate before committing:
make check # Runs codespell, ruff check, pyright, and pytest
For more details on how our solutions are structured, see Project Structure and My Advent of Code Template v3.
Python Virtual Environments
Under the hood, tools like uv still create and maintain a standard virtual environment (venv) — an isolated Python context per project so package versions never conflict across projects or with your operating system.
Always work inside a project virtual environment rather than installing packages globally.
If you are working on a standalone project outside this repository without uv, you can fall back to Python’s built-in venv module:
# Create .venv/ (never commit .venv/ to Git)
python -m venv .venv
# Activate it
source .venv/bin/activate # Linux / macOS
.venv\Scripts\Activate.ps1 # Windows PowerShell
# Install packages
python -m pip install some-package
Using Conda
Conda is an alternative environment and package manager that can also bundle non-Python system libraries (such as ffmpeg or graphviz). For this repository, uv with pyproject.toml replaces our older Conda setup, though if you prefer Conda you can still create a Python 3.13+ environment with conda create -n aoc-env python=3.13.