| 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 |