Installation

Supported installation model

The current live build is a Python source application. KOPR can run natively on Linux and natively on Windows. On Windows, WSL 2 is used only as an optional backend for the external Astrometry.net solve-field command; the KOPR GUI, FITS files, working directories and local index library remain on the Windows side.

KOPR first prefers a native solve-field executable on PATH. When KOPR is running as a native Windows Python process and no native solver is available, it probes the default WSL distribution. A non-default distribution can be selected with KOPR_WSL_DISTRIBUTION.

Requirements

The R22 source contains alb3.py, but the approximately 32.7 MB DE440s kernel is not bundled. When data/de440s.bsp is absent, KOPR opens a first-start progress dialog for a verified download. Cancel leaves KOPR usable with the non-fatal legacy ephemeris fallback, while Retry starts another attempt without requiring an application restart. The target file is replaced atomically only after verification, and temporary .part data are cleaned up by the downloader. A manual verified attempt can be started with python de440s_fetch.py; an existing kernel can be selected with KOPR_DE440S. The removed astrolib3 directory is not an installation dependency.

Optional JPL support can be added inside the same virtual environment:

python -m pip install astroquery

Do not make astroquery a hard runtime requirement when offline WCCD operation is sufficient.

Ubuntu/Linux installation

1. Install operating-system packages

   sudo apt update
   sudo apt install python3 python3-venv python3-pip unzip astrometry.net

   The Ubuntu astrometry.net package supplies the solve-field command. KOPR manages its own application-local index set separately.

2. Extract the complete source archive

   Keep the directory structure intact. In the example below, replace the archive name and extracted directory name with the actual names.

   mkdir -p ~/kopr
   cd ~/kopr
   unzip ~/Downloads/kopr-live-python3.zip
   cd path/to/the/directory/that/contains/kopr.py

   Confirm the working directory:

   test -f kopr.py && echo "KOPR source root found"

3. Create an isolated Python environment

   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip

   A virtual environment avoids the externally-managed-environment/PEP 668 error produced when pip is used against the operating-system Python.

4. Install the Python dependencies

   Download the KOPR requirements list into the source root, then run:

   python -m pip install -r kopr-python-requirements.txt

   Equivalent direct command:

   python -m pip install PyQt5 matplotlib numpy astropy requests jplephem ExifRead rawpy scipy urllib3

   rawpy provides the LibRaw backend required for automatic DSLR RAW → TG FITS materialization. When pending or stale RAW representations are found without this dependency, KOPR reports DSLR RAW extraction unavailable; existing FITS may still open, but physical RAW is never loaded directly.

5. Verify the installation

   python --version
   command -v solve-field
   python -c "import PyQt5, numpy, scipy, astropy, matplotlib, requests, jplephem, exifread, rawpy; print('Python dependencies OK')"

   You can also download the non-destructive installation checker into the source root and run:

   python check-kopr-install.py .

   For an R22 distribution, also run the dependency-light release validator:

   python3 validate_performance_release.py

   Use --json when machine-readable output is required.

6. Start KOPR

   source .venv/bin/activate
   python kopr.py

Astrometry.net and local indexes

Two separate components are required:

1. The solver: the external solve-field program.
2. The index files: local FITS data files used by the solver.

WStack resolves a usable solver backend before it checks or downloads the large index library:

1. use native solve-field when it is on PATH;
2. on native Windows, otherwise probe solve-field in the selected WSL distribution;
3. only after solver preflight succeeds, discover local 4100/4200 families and install the established 4206–4214 set when it is missing.

The application-local indexes remain in the KOPR directory on both Linux and Windows:

astrometry-index/4100/   # optional Tycho-2 family
astrometry-index/4200/   # established automatic-download family

KOPR reports the available families and wide-field recommendation in [INDEX] terminal lines. Missing 4100 indexes produce a warning only; they do not block a valid 4200 installation. Automatic downloading still installs 4206–4214.

The downloader preserves partial files after cancellation and resumes them later. Keep sufficient free disk space and make the KOPR source directory writable. Do not create an empty completion marker manually; readiness is checked against the actual index FITS files.

Native Windows installation with the WSL Astrometry.net backend

KOPR itself runs as a normal Windows Python application. Ubuntu does not need to be opened for each observing session; WSL is started automatically when astrometry calls solve-field.

1. Install KOPR and Python on Windows

   Extract the complete KOPR archive to a writable directory on a local disk, for example C:\KOPR. Install a supported 64-bit Python 3.10 or newer and create a virtual environment in PowerShell:

   cd C:\KOPR
   py -3 -m venv .venv
   .\.venv\Scripts\Activate.ps1
   python -m pip install --upgrade pip
   python -m pip install -r docs\files\kopr-python-requirements.txt

   If PowerShell blocks activation, use Set-ExecutionPolicy -Scope Process Bypass for that terminal session or activate from cmd.exe with .venv\Scripts\activate.bat.

2. Install WSL 2 and Ubuntu

   Open PowerShell as Administrator:

   wsl --install -d Ubuntu

   Restart Windows when requested. If normal download fails, use:

   wsl --install --web-download -d Ubuntu

3. Initialize Ubuntu once

   Open Ubuntu from the Start menu and create the Linux username and password requested during first initialization. Characters are not displayed while typing the password.

4. Install Astrometry.net inside Ubuntu

   sudo apt update
   sudo apt install -y astrometry.net

   If the package is not found:

   sudo apt install -y software-properties-common
   sudo add-apt-repository universe
   sudo apt update
   sudo apt install -y astrometry.net

5. Verify the solver in Ubuntu

   command -v solve-field
   solve-field --help

   The command path is normally /usr/bin/solve-field.

6. Verify the solver from Windows

   Close Ubuntu and run in ordinary PowerShell:

   wsl.exe -d Ubuntu -- sh -lc "command -v solve-field"
   wsl.exe -d Ubuntu -- sh -lc "command -v solve-field >/dev/null && solve-field --help >/dev/null && echo ASTROMETRY_OK"

   The second command should print ASTROMETRY_OK.

7. Confirm WSL 2

   wsl --list --verbose

   The selected distribution must show version 2. Convert an older installation with:

   wsl --set-version Ubuntu 2

8. Select a non-default distribution when necessary

   The current implementation probes the default WSL distribution unless an explicit override is supplied. For the current PowerShell session:

   $env:KOPR_WSL_DISTRIBUTION = "Ubuntu-24.04"

   Use the exact name shown by wsl --list --verbose. KOPR does not automatically iterate through every installed distribution.

9. Start KOPR natively

   cd C:\KOPR
   .\.venv\Scripts\Activate.ps1
   python kopr.py

   At astrometry start, KOPR first looks for a native solver and then uses WSL if necessary. Windows paths are translated with wslpath; resulting WCS files are written back into the original Windows working directory.

Updating a live source installation

1. Close KOPR and wait for any WStack worker to finish.
2. Back up config-files/, comet-data/ and obs-data/.
3. Extract the new live archive into a new directory rather than overwriting a running installation blindly.
4. Create or reuse a virtual environment and install the requirements.
5. Copy your backed-up user-data directories into the new source root.
6. Run the installation checker, then start KOPR.

WStack session state is stored with each working directory in pipeline_state.json; it is not part of the central KOPR configuration backup.

Installation diagnostics

Run check-kopr-install.py. On native Windows it accepts either a native solver or a verified WSL solver backend.

Continue with Getting started after the required checks pass.

External references

• Python documentation: virtual environments
• Microsoft: install WSL
• Microsoft: basic WSL commands
• Astrometry.net code and index overview