Installation, Upgrade and Uninstallation

简体中文

Paper Atlas runs as a local web service. There are two supported ways to use it:

1. Source mode — run start.sh / start.bat; the launcher creates a private Python environment.
2. Portable build — build (or download) a single executable; no Python required.

Both modes use the same data/ folder format.

---

Requirements

Item	Requirement
OS	Windows 10/11, Ubuntu 20.04+, Debian, Fedora, macOS
Python (source mode)	3.10 or newer
Disk	~600 MB for the private environment + space for PDFs
Network	Required for search/download and remote AI APIs; not required for reading existing local files
Permissions	No administrator rights; everything is installed inside the project folder

The launcher can download a private Python interpreter and uv into .tools/ when no suitable system Python is available. Set PAPER_ATLAS_NO_PROMPT=1 for unattended installs.

---

Source installation

Windows

1. Install Python 3.10+ from python.org and enable Add python.exe to PATH.
2. Open the project folder.
3. Double-click start.bat, or run:

start.bat

Linux / macOS

cd Paper_Atlas1.5
chmod +x start.sh
./start.sh

The launcher:

1. Finds a suitable Python (or downloads one into .tools/python).
2. Creates .venv/.
3. Installs requirements.txt.
4. Creates data/ on first start.
5. Starts the dashboard and opens the browser.

First start

• URL: http://127.0.0.1:8765
• A fixed access code is generated and printed in the console; it is also stored in data/config.json.
• Enter the code on the login page. Change it later in Settings → Network.
• If the browser does not open automatically, open the URL manually.

Environment check

python launcher.py --check

This prints the detected Python, virtual environment, data folder and optional modules without starting the server.

Manual dependency installation

If you prefer to manage the environment yourself:

python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt
python app.py --host 127.0.0.1 --port 8765

Optional browser fallback for arXiv downloads:

python -m pip install -r requirements-optional.txt
python -m playwright install firefox

Then enable Settings → Downloads → Browser fallback.

---

Configuration

Do not edit files unless the UI does not expose the option.

File	Purpose
data/config.json	AI provider, model, base URL, API keys, access code, port, downloads, review settings
data/library.json	arXiv download index
data/review/review.db	papers, projects, analyses, notes, annotations
data/jobs.db	durable download jobs
.env	optional environment overrides (not included)

Environment variables override data/config.json. See .env.example.

API keys

• DeepSeek key: Settings → AI → API Key.
• Ollama: no key required; start ollama serve and select Ollama.
• Elsevier: optional; without it journal search falls back to OpenAlex/Crossref.
• Keys are stored locally in data/config.json and masked in the UI. Never commit this file.

---

Data folder

Default locations:

Mode	Data folder
Source	<project>/data/
Portable build	data/ next to the executable
Read-only install (frozen)	%LOCALAPPDATA%\PaperAtlas\data or ~/.local/share/paper-atlas/data

A complete data folder contains PDFs, SQLite databases, settings and optionally a Firefox profile. Treat it as private user data.

Backup

python scripts/backup_data.py

The script uses the SQLite backup API, excludes firefox-profile/, and keeps the last three backups under data/backups/.

Verify

python scripts/verify_data.py
python scripts/verify_data.py --backup data/backups/<timestamp>

Move to another machine

1. Stop Paper Atlas.
2. Copy the whole project folder and data/ (or use a backup).
3. Start on the new machine.
4. If the old machine used absolute PDF paths, open Local papers once; the arXiv sync repairs paths. Journal PDFs use paths relative to data/review/pdfs/.

---

Upgrade

1. Back up data/ first.
2. Stop the running service.
3. Replace the code folder with the new version. Keep your existing data/ folder.
4. Start normally. Pending database migrations are applied automatically and a schema version is recorded.
5. To run the migration explicitly with an automatic backup:

python scripts/migrate_schema.py
python scripts/verify_data.py

If a migration fails:

python scripts/migrate_schema.py --restore-on-failure

The pre-migration database is in data/backups/<timestamp>/review.db.

Never delete data/ to “fix” an upgrade. Restore from backup instead.

---

Portable build

Build on the same OS family you intend to run on.

# Linux / macOS
./build.sh --clean --zip

# Windows
build.bat --clean --zip

Outputs:

• dist/PaperAtlas or dist/PaperAtlas.exe
• PaperAtlas-<platform>.zip when --zip is used

The executable bundles Python, dependencies, templates, static assets and PDF.js. It still writes user data to data/ next to the executable (or the per-user folder if that location is read-only).

---

Uninstallation

Paper Atlas does not install system services, registry entries or global packages. Uninstalling means deleting files.

Source installation

1. Stop the server (Ctrl+C in the terminal, or close the launcher window).
2. Delete the project folder, including:
   • .venv/
   • .tools/
   • data/
3. If you created a desktop shortcut with --shortcut, delete it manually.
4. Optional: remove a .env file if you created one.

Portable build

1. Stop the app.
2. Delete PaperAtlas / PaperAtlas.exe and the adjacent data/ folder.
3. On a read-only installation, also delete:
   • Windows: %LOCALAPPDATA%\PaperAtlas
   • Linux: ~/.local/share/paper-atlas
   • macOS: ~/Library/Application Support/PaperAtlas

Keep your research data

If you may reinstall later, keep a copy of data/ (or a data/backups/ snapshot). PDFs and notes are not recoverable once deleted.

---

Troubleshooting installation

See TROUBLESHOOTING.md. The most common causes are:

• Python older than 3.10;
• no network during the first dependency install;
• port 8765 already in use;
• a stale .venv/ copied from another machine (delete it and rerun start.sh).