advent-of-code

library2025.6.0pypiunverified

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).

devops

pip install advent-of-code

INSTALL

IMPORT

SIG · ADVENT-OF-CODE

advent-of-code

devopsenv2025.6.0

Install

2.1s avg

Import

—

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2024.21.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.000s · 19.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.1s · import 0.000s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

download_input

✓ from aoc.api import download_input

✗ import aoc.download_input

Directly import functions from the 'aoc.api' submodule for programmatic use.

submit

✓ from aoc.api import submit

✗ from advent_of_code import submit

The top-level 'advent_of_code' package does not directly expose helper functions; use 'aoc.api'.

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>

aoc --version

Debug

Known issues

breakingThe 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.

affects: 2023.0.0 and above

gotchaThe `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.

affects: All

gotchaThe 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.

affects: All

gotchaRepeatedly 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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'advent_of_code'

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.

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'

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.

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`).

Upgrade

Version history

2025.6.0latest on PyPI · released Mar 7, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

49 hits · last 30 days

node

OpenAI (training)

Resources

No resource links recorded.