Skip to content

installation.md

Latest commit

 

History

History
303 lines (221 loc) · 10.6 KB

installation.md

File metadata and controls

303 lines (221 loc) · 10.6 KB
Raw
title Installation
status reviewed
last_verified 2026-10-10
verified_against packages/auto_apply/pyproject.toml extras; CI matrix; INSTALL-WINDOWS.bat / INSTALL-MAC.command / INSTALL-LINUX.sh
audience users

Installation

This is the only installation document. Earlier copies at /INSTALL.md and docs/INSTALL.md have been retired; if you find a third one, it is stale.

Before you start

!!! warning "AutoApply is pre-alpha"

It has never completed an application submission. Read
[STATUS.md](../STATUS.md) before you install, so you know what you are
getting.

Requirements
Python 3.10 or newer. CI exercises 3.10 and 3.12
Browser Chrome, Chromium, Firefox or Edge. Required — AA refuses to start a session without one (ADR-013)
Operating system Windows, macOS or Linux. All three are in CI
Disk ~300 MB for a core install. Optional tiers are much larger
Memory 4 GB is the design target
Privileges None. AA does not need administrator rights
Accounts None. No API key, no subscription, no sign-up

Check your Python:

python --version

If that prints 3.9 or lower, or "command not found", try python3 --version.

The easiest way — download and double-click

No Python, no developer tools, no admin rights, no typing commands.

  1. On the AA repository page, click the green Code button, then Download ZIP.
  2. Unzip it (on Windows: right-click the ZIP, then Extract All…). Running the installer from inside the ZIP does not work; it says so.
  3. Open the unzipped folder and run the installer for your computer:
Your computer What to do
Windows Double-click INSTALL-WINDOWS.bat. If a blue "Windows protected your PC" box appears, click More info, then Run anyway.
macOS Double-click INSTALL-MAC.command. If macOS says it cannot be opened, open System Settings → Privacy & Security and click Open Anyway. Or open Terminal, type sh (with a space), drag the file into the window and press Return.
Linux Open a terminal in the folder and run sh INSTALL-LINUX.sh
  1. Read the plan it shows, type y and press Enter.

The installer copies AutoApply out of the folder you downloaded (no second download of the source), installs uv into ~/.auto_apply, builds the environment on a suitable Python already on the computer (used as found, never changed or removed) or, when there is none, on its own Python downloaded into the same folder, adds a shortcut (macOS: Desktop; Linux: applications menu; Windows: Start-menu Programs folder), and offers to start AutoApply. The downloaded folder can then be deleted. Re-running the installer is safe: it repairs what is missing and never duplicates.

Method 0 — one-command installer

No Python, no developer tools, no admin rights needed. One command fetches a short, readable bootstrap, which installs uv and a uv-managed Python inside a single AA folder (default ~/.auto_apply), fetches the AA source, and hands over to AA's own --install — which builds the environment, writes the launcher, and reports what it found. Nothing is installed system-wide; your browser is detected, never installed. On a Mac, none of this needs the Command Line Tools: no git, no compiler — wheels only.

macOS / Linux (needs only curl, which both ship):

curl -fsSL https://raw.githubusercontent.com/Liebmann5/AA/main/packages/auto_apply/install.sh | sh

Windows (PowerShell, which Windows ships):

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/Liebmann5/AA/main/packages/auto_apply/install.ps1 | iex"

The bootstrap shows exactly what it will download, the approximate sizes, and where everything goes, and asks before downloading. uv and Python are verified against pinned checksums (install_pins.txt in the repo); a failed verification deletes the download and stops the install. Offline / USB: install.sh --root /media/usb/AutoApply --archive AA-src.tar.gz --offline installs from a pre-populated folder with no network (one prepared copy per operating system — uv and Python builds are per-platform).

!!! warning "Requires the first release"

The bootstrap's default source is the release archive **plus its
checksum file**: the release process publishes `AA-src.tar.gz` and
`SHA256SUMS.txt` as assets, and the bootstrap verifies the archive
against them. A release without the checksum file makes the bootstrap
REFUSE — an unverified source archive is not acceptable for an
installer that refuses an unverified uv. The explicit, printed opt-out
is `--allow-unverified-source`. Until the first GitHub release exists,
use the download-and-double-click route above, pass
`--archive <path-to-a-source-tar.gz>`, or use Method 1. Piping a
script from the internet is a trust decision: the script and the pins
file are in the repository to read first, and the executables it runs
are checksum-verified rather than channel-trusted.

Method 1 — from a source checkout (recommended today)

AA is not yet published to PyPI. pip install auto_apply does not work; any document that tells you otherwise is stale.

git clone https://github.com/Liebmann5/AA.git
cd AA
pip install uv
uv sync

uv sync creates .venv, installs the package in editable mode, installs the development group, and honours the committed uv.lock.

Run it:

uv run --package auto_apply python -m auto_apply

Verify the checkout:

cd packages/auto_apply
uv run pytest tests -q -p no:cacheprovider -rs

Expect 1384 passed, 2 skipped, plus roughly ten skips if you have no Chrome driver installed.

Method 2 — pip, from the checkout

If you do not want uv and only want to run AA:

git clone https://github.com/Liebmann5/AA.git
cd AA
pip install packages/auto_apply
auto-apply

This installs runtime dependencies only. The test suite will not run, because the development tooling lives in a PEP 735 dependency group that pip's extras syntax cannot read.

Method 3 — USB portable

For a machine where you cannot install anything.

cd /media/usb/autoapply
python -m auto_apply --portable

Everything AA writes goes to ./data/ next to the working directory — profile, database, logs, reports, caches.

!!! warning "Containment is not yet proven"

`[PARTIAL]`. Portable mode runs. Two former leaks are now contained
in-process, on every launch path: Selenium Manager's driver cache
(`SE_CACHE_PATH`, with its usage statistics opted out) and the
snap-Firefox geckodriver profile root both resolve inside the data
directory.

Known gaps remain: Playwright browsers and the Hugging Face / GPT4All
model caches use their per-OS defaults unless the launcher environment
covers them, and pip-installed SpaCy models always live in the Python
environment they were installed into. The uninstaller's discovery list
knows these locations and reports them; it never removes shared caches.

Treat "leaves no trace" as an intention, not a guarantee, until
[STATUS.md](../STATUS.md) says otherwise.

A prebuilt PyInstaller executable is [PLANNED]. There is no Releases download. Do not follow a document that offers one.

Optional feature tiers

Every extra is opt-in. Nothing below is required for AA to work, and nothing is downloaded without you asking for it.

Extra Install Adds Size
nlp uv sync --extra nlp SpaCy entity extraction, semantic title matching small; model separate
semantic uv sync --extra semantic sentence-transformers role alignment ~400 MB
browser uv sync --extra browser Playwright ~300 MB plus browsers
ai uv sync --extra ai GPT4All, a local LLM for open-ended answers model 4–8 GB on first use
stealth uv sync --extra stealth undetected-chromedriver small
captcha uv sync --extra captcha offline audio transcription ~100 MB
research uv sync --extra research Parquet export (pyarrow, pandas) ~150 MB
all uv sync --extra all Everything above large

Installing with pip instead of uv:

pip install "packages/auto_apply[nlp]"

The SpaCy model is a separate, deliberate download

uv run python -m spacy download en_core_web_lg

It is not downloaded automatically. AA does not put anything on your device without asking — that is a hard principle, not a default.

!!! note "The model changes your results"

Installing the model measurably changes vetting behaviour: with it, several
job-title filters become more permissive. Runs with and without it are not
directly comparable. If you are collecting research data, record which
configuration you used.

Playwright browsers

uv run python -m playwright install firefox

Verify your installation

python -m auto_apply --check-config

This prints what AA detected — Python version, available browsers, optional dependencies, data directory — and exits without starting a session. Paste this output into any bug report.

First run

python -m auto_apply          # GUI
python -m auto_apply --cli    # terminal

The first launch opens the setup wizard. Continue with Quick Start.

Uninstalling

# uv checkout
rm -rf .venv

# pip install
pip uninstall auto_apply

Your data lives in AA's data directory, which is not removed by either command. In portable mode it is the data/ folder next to where you ran AA; otherwise --check-config prints the path. Delete it yourself when you want the data gone — AA will not delete your profile on your behalf.

Troubleshooting

Symptom Cause and fix
pip install auto_apply — package not found AA is not on PyPI yet. Use Method 1
No module named tkinter Debian and Ubuntu split it out: sudo apt install python3-tk. Or use --cli, which needs no GUI toolkit
Session refuses to start, "no browser" AA requires a browser. Install Chrome, Chromium, Firefox or Edge
import hypothesis fails during tests You installed with pip rather than uv sync. Dev tooling is a PEP 735 group
Browser launches then exits immediately Headless environment with no display. Set headless mode in your profile
Works on one machine, not another Run --check-config on both and compare. Usually a missing browser or a different Python

More in the FAQ.