# Getting started

## Prerequisites

- Python 3.10 or newer (pip on 3.9 finds no release it can install; see [Troubleshooting](<https://geiserx.github.io/Wayback-Archive/troubleshooting/#pip-cannot-install-it-python-39>))
- pipx or pip

## From PyPI

```
pipx install wayback-archive
```

pipx gives the command its own environment. Inside a virtual environment, pip works the same way:

```
pip install wayback-archive
```

Homebrew Python and the system Python on Debian and Ubuntu refuse a bare `pip install` with `externally-managed-environment`, which is why pipx comes first. See [Troubleshooting](<https://geiserx.github.io/Wayback-Archive/troubleshooting/#pip-refuses-to-install-externally-managed-environment>) for both fixes.

Then give it one Wayback Machine URL:

```
wayback-archive "https://web.archive.org/web/20051231235226/http://www.python.org/" --max-files 50
```

The copy lands in `./output` (`-o DIR` changes it). `--max-files 50` keeps the first try to about a minute, and on this snapshot the homepage, its stylesheet and its images are all within those 50 files, so the copy opens styled. Drop `--max-files` to fetch the whole site. On another site a short run can stop before a stylesheet that is only reached through `@import`, because the crawl fetches files in the order it finds them. Every setting is a flag or an environment variable (`WAYBACK_URL`, `MAX_FILES`, ...), listed in [Configuration](<https://geiserx.github.io/Wayback-Archive/configuration/index.md>) and by `wayback-archive --help`; per-shell examples are in [Usage](<https://geiserx.github.io/Wayback-Archive/usage/index.md>).

## What a finished run looks like

Each file prints a numbered line while it downloads. The run ends with a block like this one:

```
======================================================================
Download Complete!
======================================================================
Output directory: ./output
Files successfully downloaded: 50
Files failed: 0
Files skipped (duplicates): 0
Total files processed: 50
======================================================================
```

`Files failed` (none here) counts pages and files the archive does not have at that timestamp or any nearby one; their links stay broken in the copy.

Open the copy straight from disk:

```
open output/index.html        # macOS
xdg-open output/index.html    # Linux
start output\index.html       # Windows
```

A browser that blocks scripts on `file://` pages can use a local server instead: `cd output && python3 -m http.server 8000`, then open `http://localhost:8000`.

## With Docker

The image runs the same command; pass settings with `-e` and mount a directory on `/output` to keep the copy:

```
docker run --rm \
  -e WAYBACK_URL="https://web.archive.org/web/20051231235226/http://www.python.org/" \
  -e MAX_FILES=50 \
  -v "$PWD/output:/output" \
  drumsergio/wayback-archive:1.6.0
```

Tags are the release version (`1.6.0`) and its minor line (`1.6`); there is no `latest`.

The container runs as an unprivileged user (uid 1000). On Linux, create `output` before the run (Docker would create it owned by root) and add `--user "$(id -u):$(id -g)"` so the files belong to you.

## From source

```
git clone https://github.com/GeiserX/Wayback-Archive.git
cd Wayback-Archive

# Optional: create a virtual environment
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

pip install -r config/requirements.txt
WAYBACK_URL="https://web.archive.org/web/20051231235226/http://www.python.org/" python3 -m wayback_archive.cli
```

To get the `wayback-archive` command from a checkout, install it in editable mode with `pip install -e .`.
