Debian Codegraph @

doc/intro/installation_offline.rst

raw
1 .. _installation_offline:
2
3 Offline Installation
4 ====================
5
6 .. meta::
7 :description: Offline installation guide for DataLab on systems without internet access
8 :keywords: DataLab, offline, installation, Python, pip, wheel, no internet, Windows, Linux, macOS
9
10 This guide explains how to install DataLab on a system **without internet access**.
11
12 .. note::
13
14 This page focuses on **offline installation using pip** (Python package manager).
15 For other offline installation methods, see the :ref:`installation_offline_alternatives`
16 section below.
17
18 Offline installation via pip
19 ----------------------------
20
21 :octicon:`info;1em;sd-text-info` :bdg-info-line:`GNU/Linux` :bdg-info-line:`Windows` :bdg-info-line:`macOS`
22
23 This method works on **any operating system** with **Python 3.9 to 3.14**.
24 It assumes you have an online machine available to download packages, and a separate
25 offline machine where DataLab will be installed.
26
27 Requirements
28 ------------
29
30 Offline machine
31 ^^^^^^^^^^^^^^^
32
33 - GNU/Linux, Windows, or macOS
34 - Python 3.9 to 3.14 installed with the **same major version** as the online machine
35 - No assumptions regarding installed packages
36
37 .. important::
38
39 **Version compatibility is critical:**
40
41 - ✅ **Allowed:** Python 3.10.2 ↔ Python 3.10.11 (same major version)
42 - ❌ **Not allowed:** Python 3.10.x ↔ Python 3.11.x (different major versions)
43
44 SciPy, NumPy, and scikit-image are highly dependent on the Python major version.
45 Both machines must use the same major Python version for reliable offline installation.
46
47 To check your Python version, run:
48
49 .. code-block:: console
50
51 python --version
52
53 Online machine
54 ^^^^^^^^^^^^^^
55
56 - Windows, Linux, or macOS
57 - Python with the **same major version** as the offline machine
58 - ``pip`` installed
59
60 Preparing packages (online machine)
61 -----------------------------------
62
63 Download all required **Wheel packages** for offline installation.
64
65 Create a folder for packages
66 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
67
68 .. tab-set::
69
70 .. tab-item:: Windows
71
72 .. code-block:: console
73
74 mkdir C:\datalab-offline
75 cd C:\datalab-offline
76
77 .. tab-item:: GNU/Linux / macOS
78
79 .. code-block:: console
80
81 mkdir ~/datalab-offline
82 cd ~/datalab-offline
83
84 Download DataLab and dependencies
85 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
86
87 .. tab-set::
88
89 .. tab-item:: Windows
90
91 .. code-block:: console
92
93 pip download datalab-platform --dest C:\datalab-offline
94
95 .. tab-item:: GNU/Linux / macOS
96
97 .. code-block:: console
98
99 pip download datalab-platform --dest ~/datalab-offline
100
101 This command downloads:
102
103 - ``datalab-platform``
104 - ``sigima``
105 - ``plotpy``
106 - ``guidata``
107 - ``pythonqwt``
108 - ``numpy``, ``scipy``, ``scikit-image``, and other dependencies
109
110 Expected folder structure
111 ^^^^^^^^^^^^^^^^^^^^^^^^^
112
113 After downloading, your folder should contain files similar to:
114
115 .. code-block:: text
116
117 datalab-offline/
118 ├─ datalab_platform‑1.x.x‑py3‑none‑any.whl
119 ├─ sigima‑1.x.x‑py3‑none‑any.whl
120 ├─ plotpy‑x.x.x‑py3‑none‑any.whl
121 ├─ guidata‑3.x.x‑py3‑none‑any.whl
122 ├─ pythonqwt‑x.x.x‑py3‑none‑any.whl
123 ├─ numpy‑...‑cp310‑cp310‑[platform].whl
124 ├─ scipy‑...‑cp310‑cp310‑[platform].whl
125 ├─ scikit_image‑...‑cp310‑cp310‑[platform].whl
126 └─ ...
127
128 .. note::
129
130 The ``[platform]`` suffix in the wheel filenames will vary depending on your
131 system: ``win_amd64`` (Windows), ``manylinux`` (Linux), ``macosx`` (macOS).
132
133 Transfer to offline machine
134 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
135
136 Transfer the ``datalab-offline`` folder to your offline machine using:
137
138 - USB drive
139 - Network share
140 - Any other approved method in your organization
141
142 Offline installation
143 --------------------
144
145 On the offline machine, navigate to the folder and install DataLab.
146
147 Navigate to the folder
148 ^^^^^^^^^^^^^^^^^^^^^^
149
150 .. tab-set::
151
152 .. tab-item:: Windows
153
154 .. code-block:: console
155
156 cd C:\datalab-offline
157
158 .. tab-item:: GNU/Linux / macOS
159
160 .. code-block:: console
161
162 cd ~/datalab-offline
163
164 Install DataLab offline
165 ^^^^^^^^^^^^^^^^^^^^^^^
166
167 .. code-block:: console
168
169 python -m pip install --no-index --find-links . datalab-platform
170
171 The ``--no-index`` option tells pip not to connect to the internet, and
172 ``--find-links .`` tells pip to look for packages in the current directory.
173
174 Verification
175 ------------
176
177 To verify that DataLab is installed correctly, run:
178
179 .. code-block:: console
180
181 python -m datalab.app
182
183 This should launch the DataLab application.
184
185 Optional: Virtual environment
186 -----------------------------
187
188 It is recommended to install DataLab in a virtual environment to avoid conflicts
189 with other Python packages.
190
191 Create and activate a virtual environment
192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
193
194 .. tab-set::
195
196 .. tab-item:: Windows
197
198 .. code-block:: console
199
200 python -m venv C:\venvs\datalab
201 C:\venvs\datalab\Scripts\activate
202
203 .. tab-item:: GNU/Linux / macOS
204
205 .. code-block:: console
206
207 python -m venv ~/venvs/datalab
208 source ~/venvs/datalab/bin/activate
209
210 Install DataLab in the virtual environment
211 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
212
213 .. tab-set::
214
215 .. tab-item:: Windows
216
217 .. code-block:: console
218
219 python -m pip install --no-index --find-links C:\datalab-offline datalab-platform
220
221 .. tab-item:: GNU/Linux / macOS
222
223 .. code-block:: console
224
225 python -m pip install --no-index --find-links ~/datalab-offline datalab-platform
226
227 Launch DataLab
228 ^^^^^^^^^^^^^^
229
230 .. code-block:: console
231
232 python -m datalab.app
233
234 WinPython for offline usage
235 ---------------------------
236
237 :octicon:`info;1em;sd-text-info` :bdg-info-line:`Windows`
238
239 `WinPython <https://winpython.github.io/>`_ is particularly well-suited for offline
240 installations as it provides a portable, self-contained Python environment.
241
242 Prepare on online machine
243 ^^^^^^^^^^^^^^^^^^^^^^^^^
244
245 1. Download WinPython with the **same major Python version** as your target system
246 2. Install WinPython
247 3. Open the *WinPython Command Prompt*
248 4. Download packages:
249
250 .. code-block:: console
251
252 pip download datalab-platform --dest C:\datalab-offline
253
254 Install on offline machine
255 ^^^^^^^^^^^^^^^^^^^^^^^^^^
256
257 1. Transfer WinPython and the ``datalab-offline`` folder to the offline machine
258 2. Open the *WinPython Command Prompt*
259 3. Install DataLab:
260
261 .. code-block:: console
262
263 cd C:\datalab-offline
264 python -m pip install --no-index --find-links . datalab-platform
265
266 Benefits of WinPython
267 ^^^^^^^^^^^^^^^^^^^^^
268
269 - **Portable:** No installation required, can run from USB drive
270 - **Self-contained:** All dependencies included
271 - **Ideal for restricted environments:** No admin rights needed
272 - **Multiple versions:** Can have multiple Python versions side by side
273
274 Quick summary
275 -------------
276
277 The complete workflow in four steps:
278
279 1. **On online machine:** Download packages
280
281 .. code-block:: console
282
283 pip download datalab-platform --dest /path/to/datalab-offline
284
285 2. **Transfer:** Copy the ``datalab-offline`` folder to the offline machine
286
287 3. **On offline machine:** Install offline
288
289 .. code-block:: console
290
291 python -m pip install --no-index --find-links /path/to/datalab-offline datalab-platform
292
293 4. **Verify:** Launch DataLab
294
295 .. code-block:: console
296
297 python -m datalab.app
298
299 .. _installation_offline_alternatives:
300
301 Other offline installation methods
302 ----------------------------------
303
304 While this guide focuses on pip-based offline installation, DataLab can also be
305 installed offline using other methods:
306
307 Stand-alone installer (Windows)
308 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
309
310 :octicon:`info;1em;sd-text-info` :bdg-info-line:`Windows` **Recommended for offline installation**
311
312 The **all-in-one installer** is the simplest way to install DataLab offline on Windows.
313 It does not require any Python distribution or internet connection on the target machine.
314
315 **Advantages:**
316
317 - No Python installation required
318 - Single executable file
319 - Self-contained with all dependencies
320 - No internet connection needed during installation
321 - Works on air-gapped systems
322
323 **How to use:**
324
325 1. On a machine with internet access, download the installer from the
326 `DataLab Releases <https://github.com/DataLab-Platform/DataLab/releases>`_ page
327 2. Transfer the installer executable to the offline machine (USB drive, network share, etc.)
328 3. Run the installer on the offline machine
329
330 For more information, see :ref:`install_aioinstaller`.
331
332 WinPython distribution (Windows)
333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
334
335 :octicon:`info;1em;sd-text-info` :bdg-info-line:`Windows`
336
337 `DataLab-WinPython <https://github.com/DataLab-Platform/DataLab-WinPython>`_ is a
338 portable Python distribution that includes DataLab and all its dependencies.
339
340 **Advantages:**
341
342 - Portable (can run from USB drive)
343 - No installation required
344 - Includes full Python environment
345 - Can be extended with additional packages
346 - Ideal for restricted environments
347
348 **How to use:**
349
350 1. Download DataLab-WinPython from the
351 `releases page <https://github.com/DataLab-Platform/DataLab-WinPython/releases>`_
352 2. Transfer to the offline machine
353 3. Extract and run
354
355 For more information, see :ref:`install_winpython`.
356
357 Conda offline installation
358 ^^^^^^^^^^^^^^^^^^^^^^^^^^
359
360 :octicon:`info;1em;sd-text-info` :bdg-info-line:`GNU/Linux` :bdg-info-line:`Windows` :bdg-info-line:`macOS`
361
362 Conda packages can also be installed offline using a similar approach to pip:
363
364 1. **On online machine:** Download the conda package and dependencies:
365
366 .. code-block:: console
367
368 conda create -n datalab-offline --download-only --json conda-forge::datalab
369
370 Or use ``conda list --explicit`` to create a specification file.
371
372 2. **Transfer** the downloaded packages to the offline machine
373
374 3. **On offline machine:** Install from the local packages:
375
376 .. code-block:: console
377
378 conda create -n datalab --offline -c file:///path/to/packages datalab
379
380 For more information about offline conda installation, see the
381 `Conda documentation <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-pkgs.html#installing-packages-offline>`_.
382
383 For standard online installation, see :ref:`install_conda`.
384
385 .. seealso::
386
387 For standard online installation methods, see :ref:`installation`.