Debian Codegraph @

doc/intro/installation.rst

raw
1 .. _installation:
2
3 Installation
4 ============
5
6 .. meta::
7 :description: How to install DataLab, the open-source data analysis and visualization platform
8 :keywords: DataLab, installation, install, pip, wheel, source, Windows, Linux, macOS
9
10 .. only:: html and not latex
11
12 .. dropdown:: Quick install on Windows
13 :animate: fade-in
14 :icon: zap
15
16 Direct download link for the latest version of DataLab:
17
18 - |download_link1|
19
20 .. warning::
21
22 **Important notice for users upgrading from DataLab v0.20 or earlier:**
23
24 DataLab v1.0 introduces **breaking changes** that are **not backward compatible** with v0.20.
25
26 - **Plugins** developed for v0.20 **must be updated** to work with v1.0
27 - **API changes** affect custom code integrations
28
29 For detailed migration information, see the :ref:`migration guide <migration_v020_to_v100>`.
30
31 This section provides information on how to install DataLab on your system.
32 Once installed, you can start DataLab by running the ``datalab`` command in a terminal,
33 or by clicking on the DataLab shortcut in the Start menu (on Windows).
34
35 .. seealso::
36
37 For more details on how to execute DataLab and its command-line options,
38 see :ref:`ref-to-command-line-features`.
39
40 For installation on systems without internet access, see the
41 :ref:`offline installation guide <installation_offline>`.
42
43 How to install
44 --------------
45
46 DataLab is available in several forms:
47
48 - As a :ref:`install_conda`.
49
50 - As a Python package, which can be installed using the :ref:`install_pip`.
51
52 - :bdg-info-line:`Windows` As a stand-alone application, which does not require any
53 Python distribution to be installed. Just run the :ref:`install_aioinstaller`
54 and you're good to go!
55
56 - :bdg-info-line:`Windows` Within a ready-to-use :ref:`install_winpython`, based on
57 `WinPython <https://winpython.github.io/>`_.
58
59 - As a precompiled :ref:`install_wheel`, which can be installed using ``pip``.
60
61 - As a :ref:`install_source`, which can be installed using ``pip`` or manually.
62
63 .. seealso::
64
65 Impatient to try the next version of DataLab? You can also install the
66 latest development version of DataLab from the master branch of the
67 Git repository. See :ref:`install_development` for more information.
68
69 .. _install_conda:
70
71 Conda package
72 ^^^^^^^^^^^^^
73
74 :octicon:`info;1em;sd-text-info` :bdg-info-line:`GNU/Linux` :bdg-info-line:`Windows` :bdg-info-line:`macOS`
75
76 To install ``datalab`` package from the `conda-forge` channel (https://anaconda.org/conda-forge/datalab), run the following command:
77
78 .. code-block:: console
79
80 $ conda install conda-forge::datalab
81
82 .. _install_pip:
83
84 Package manager ``pip``
85 ^^^^^^^^^^^^^^^^^^^^^^^
86
87 :octicon:`info;1em;sd-text-info` :bdg-info-line:`GNU/Linux` :bdg-info-line:`Windows` :bdg-info-line:`macOS`
88
89 DataLab's package ``datalab-platform`` is available on the Python Package Index (PyPI)
90 on the following URL: https://pypi.python.org/pypi/datalab-platform.
91
92 Installing DataLab from PyPI with Qt is as simple as running this command
93 (you may need to use ``pip3`` instead of ``pip`` on some systems):
94
95 .. code-block:: console
96
97 $ pip install datalab-platform[qt]
98
99 Or, if you prefer, you can install DataLab without the Qt library (not recommended):
100
101 .. code-block:: console
102
103 $ pip install datalab-platform
104
105 .. note::
106
107 If you already have a previous version of DataLab installed, you can
108 upgrade it by running the same command with the ``--upgrade`` option:
109
110 .. code-block:: console
111
112 $ pip install --upgrade datalab-platform[qt]
113
114 .. _install_aioinstaller:
115
116 All-in-one installer
117 ^^^^^^^^^^^^^^^^^^^^
118
119 :octicon:`info;1em;sd-text-info` :bdg-info-line:`Windows`
120
121 DataLab is available as a stand-alone application for Windows,
122 which does not require any Python distribution to be installed.
123 Just run the installer and you're good to go!
124
125 .. figure:: /images/shots/windows_installer.png
126
127 DataLab all-in-one installer for Windows
128
129 The installer package is available in the `Releases`_ section.
130 It supports automatic uninstall and upgrade feature (no need to uninstall
131 DataLab before runinng the installer of another version of the
132 application).
133
134 .. warning::
135
136 DataLab Windows installer is available for Windows 7 SP1, 8, 10 and 11.
137
138 :octicon:`alert;1em;sd-text-warning` On Windows 7 SP1, before running DataLab
139 (or any other Python 3 application), you must install Microsoft Update `KB2533623`
140 (`Windows6.1-KB2533623-x64.msu`) and also may need to install
141 `Microsoft Visual C++ 2015-2022 Redistribuable package <https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170>`_.
142
143 .. _Releases: https://github.com/DataLab-Platform/DataLab/releases
144
145 .. _install_winpython:
146
147 Python distribution
148 ^^^^^^^^^^^^^^^^^^^
149
150 :octicon:`info;1em;sd-text-info` :bdg-info-line:`Windows`
151
152 DataLab is also available within a ready-to-use Python distribution, based on
153 `WinPython <https://winpython.github.io/>`_. This distribution is called
154 `DataLab-WinPython <https://github.com/DataLab-Platform/DataLab-WinPython?tab=readme-ov-file#datalab-winpython>`_
155 and is available in the `DataLab-WinPython Releases <https://github.com/DataLab-Platform/DataLab-WinPython/releases>`_
156 section.
157
158 .. figure:: /images/logos/DataLab-WinPython.png
159
160 DataLab-WinPython is a ready-to-use Python distribution including the DataLab platform.
161
162 The main difference with the all-in-one installer is that you can use the Python
163 distribution for other purposes than running DataLab, and you may also extend it
164 with additional packages. On the downside, it is also *much bigger* than the
165 all-in-one installer because it includes a full Python distribution.
166
167 .. note::
168
169 DataLab-WinPython includes `Spyder <https://www.spyder-ide.org/>`_,
170 a powerful IDE for scientific programming in Python,
171 as well as `Jupyter Notebook <https://jupyter.org/>`_ for interactive computing.
172
173 .. figure:: /images/shots/wpcp.png
174
175 DataLab-WinPython Control Panel
176
177 .. warning::
178
179 Whereas the all-in-one installer provides a monolithic package that guarantees
180 the compatibility of all its components because it cannot be modified by the user,
181 the WinPython distribution is more flexible and thus can be broken by a bad
182 manipulation of the Python distribution by the user. This should be taken into
183 account when choosing the installation method.
184
185 .. _install_wheel:
186
187 Wheel package
188 ^^^^^^^^^^^^^
189
190 :octicon:`info;1em;sd-text-info` :bdg-info-line:`GNU/Linux` :bdg-info-line:`Windows` :bdg-info-line:`macOS`
191
192 On any operating system, using pip and the Wheel package is the easiest way to
193 install DataLab on an existing Python distribution:
194
195 .. code-block:: console
196
197 $ pip install --upgrade DataLab-1.0.1-py2.py3-none-any.whl
198
199 .. _install_source:
200
201 Source package
202 ^^^^^^^^^^^^^^
203
204 :octicon:`info;1em;sd-text-info` :bdg-info-line:`GNU/Linux` :bdg-info-line:`Windows` :bdg-info-line:`macOS`
205
206 Installing DataLab directly from the source package may be done using ``pip``:
207
208 .. code-block:: console
209
210 $ pip install --upgrade datalab-1.0.1.tar.gz
211
212 Or, if you prefer, you can install it manually by running the following command
213 from the root directory of the source package:
214
215 .. code-block:: console
216
217 $ pip install --upgrade .
218
219 Finally, you can also build your own Wheel package and install it using ``pip``,
220 by running the following command from the root directory of the source package
221 (this requires the ``build`` and ``wheel`` packages to be installed):
222
223 .. code-block:: console
224
225 $ pip install build wheel # Install build and wheel packages (if needed)
226 $ python -m build # Build the wheel package
227 $ pip install --upgrade dist/datalab-1.0.1-py2.py3-none-any.whl # Install the wheel package
228
229 .. _install_development:
230
231 Development version
232 ^^^^^^^^^^^^^^^^^^^
233
234 :octicon:`info;1em;sd-text-info` :bdg-info-line:`GNU/Linux` :bdg-info-line:`Windows` :bdg-info-line:`macOS`
235
236 If you want to try the latest development version of DataLab, you can install
237 it directly from the master branch of the Git repository.
238
239 The first time you install DataLab from the Git repository, enter the following
240 command:
241
242 .. code-block:: console
243
244 $ pip install git+https://github.com/DataLab-Platform/DataLab.git
245
246 Then, if at some point you want to upgrade to the latest version of DataLab,
247 just run the same command with options to force the reinstall of the package
248 without handling dependencies (because it would reinstall all dependencies):
249
250 .. code-block:: console
251
252 $ pip install --force-reinstall --no-deps git+https://github.com/DataLab-Platform/DataLab.git
253
254 .. note::
255
256 If dependencies have changed, you may need to execute the same command as above,
257 but without the ``--no-deps`` option.
258
259 Dependencies
260 ------------
261
262 .. note::
263
264 The DataLab all-in-one installer already include all those required
265 libraries as well as Python itself.
266
267 .. include:: ../requirements.rst
268
269 .. note::
270
271 Python 3.11 and PyQt5 are the reference for production release