Advent of Code Command-Line Helper

2025.6.0 · maintenance · verified Thu Apr 16

The `advent-of-code` Python library provides a command-line tool (`aoc`) and a programmatic API for Advent of Code. It helps automate fetching inputs, scaffolding solutions, and submitting answers. While the PyPI package (version 2025.6.0) receives active updates, its officially linked GitHub repository (`https://github.com/fornwall/advent-of-code`) has been archived since November 2023. This creates a discrepancy where new PyPI versions are released without publicly updated source code. The library uses a year-ahead versioning scheme (e.g., 2025.x.x versions released in 2024).

Common errors

```
ModuleNotFoundError: No module named 'advent_of_code'
```
cause Attempting to import the library using the PyPI package name (`advent_of_code`) instead of its internal module name (`aoc`).

fix Change your import statement to `import aoc` or `from aoc.api import ...`.
```
AdventOfCodeError: A session cookie is required to access Advent of Code.
```
cause The `AOC_SESSION` environment variable is either not set or contains an invalid/expired Advent of Code session cookie.

fix Set the `AOC_SESSION` environment variable with a valid session cookie from `adventofcode.com`. Refresh your browser to get a new cookie if it's expired.
```
AttributeError: module 'aoc' has no attribute 'download'
```
cause Attempting to call `aoc.download(...)` directly. The download functionality is exposed via the `api` submodule.

fix Use `from aoc.api import download_input` and then call `download_input(...)`.
```
Error: Input already downloaded for day X.
```
cause You tried to run `aoc download <day>` for a day for which input has already been successfully fetched and saved.

fix This is a warning, not an error preventing operation. If you need to re-download, delete the existing input file first (e.g., `rm <year>/<day>/input.txt`).

Warnings

breaking The official GitHub repository for `advent-of-code` (`fornwall/advent-of-code`) has been archived since November 2023. Despite this, the PyPI package continues to receive new versions, leading to a discrepancy where publicly available source code is outdated or missing for recent releases.
Fix: Be aware that the latest source code may not be publicly available. Consider exploring forks or alternative tools if source visibility is critical for your workflow.
gotcha The `AOC_SESSION` environment variable is mandatory for most `aoc` commands and API calls that interact with the Advent of Code website (e.g., `download`, `submit`). Without it, authentication errors will occur.
Fix: Set `export AOC_SESSION="<your_session_cookie>"` in your shell environment. Find the 'session' cookie value from `adventofcode.com` in your browser's developer tools.
gotcha The library typically expects a specific directory structure (`<year>/<day_padded>.py`, `<year>/<day_padded>/input.txt`). Commands like `aoc run` and `aoc submit` rely on this structure, usually generated by `aoc init` and `aoc download`.
Fix: Always initialize your project with `aoc init <year>` and download inputs with `aoc download <day>` within the year's directory to ensure the correct file structure.
gotcha Repeatedly fetching inputs or submitting incorrect answers too quickly can lead to rate limiting or temporary bans from Advent of Code. Use the tool responsibly.
Fix: Only fetch inputs once per day. If submitting, ensure your answer is correct before attempting multiple submissions. Review Advent of Code's puzzle rules and etiquette.

Install

pip install advent-of-code Install stable version

Imports

download_input
wrong:
```
import aoc.download_input
```
correct:
```
from aoc.api import download_input
```
Directly import functions from the 'aoc.api' submodule for programmatic use.
submit
wrong:
```
from advent_of_code import submit
```
correct:
```
from aoc.api import submit
```
The top-level 'advent_of_code' package does not directly expose helper functions; use 'aoc.api'.

Quickstart

The primary way to use `advent-of-code` is via its `aoc` command-line interface. This quickstart demonstrates how to set up a new year, fetch puzzle inputs, run your solutions, and submit answers, emphasizing the critical `AOC_SESSION` environment variable for authentication.

# 1. Install the library (if you haven't already)
# pip install advent-of-code

# 2. Set your Advent of Code session cookie as an environment variable.
#    This is crucial for fetching inputs and submitting answers.
#    Find your 'session' cookie in your browser's developer tools on adventofcode.com
# export AOC_SESSION="YOUR_SESSION_COOKIE_HERE"

# 3. Initialize a directory for a specific year (e.g., 2023)
aoc init 2023

# 4. Navigate into the year directory
cd 2023

# 5. Download input and create boilerplate for a specific day (e.g., Day 1)
aoc download 1

# 6. Your solution code will be in a file like '01.py'. Edit it.

# 7. Run your solution (e.g., for Day 1)
aoc run 1

# 8. Submit your answer for Part 1 (replace <answer> with your actual result)
# aoc submit 1 1 <answer>

view raw JSON →