2018-07-08 05:28:45 +00:00
.. _installation:
2020-08-11 22:52:41 +00:00
==============
Installation
==============
2018-06-28 03:59:58 +00:00
2019-05-16 04:57:26 +00:00
.. note ::
2020-08-12 00:24:40 +00:00
If you just want to try Datasette out you don't need to install anything: see :ref: `getting_started_glitch`
2019-05-16 04:57:26 +00:00
2018-06-28 03:59:58 +00:00
There are two main options for installing Datasette. You can install it directly
on to your machine, or you can install it using Docker.
2020-08-11 22:52:41 +00:00
If you want to start making contributions to the Datasette project by installing a copy that lets you directly modify the code, take a look at our guide to :ref: `devenvironment` .
2019-05-16 10:15:03 +00:00
.. contents ::
2020-08-11 22:52:41 +00:00
:local:
.. _installation_basic:
Basic installation
==================
.. _installation_homebrew:
Using Homebrew
--------------
If you have a Mac and use `Homebrew <https://brew.sh/> `__ , you can install Datasette by running this command in your terminal::
2020-10-10 23:19:39 +00:00
brew install datasette
This should install the latest version. You can confirm by running::
datasette --version
You can upgrade to the latest Homebrew packaged version using::
brew upgrade datasette
2020-08-11 22:52:41 +00:00
2020-08-12 00:31:53 +00:00
Once you have installed Datasette you can install plugins using the following::
2020-08-11 22:52:41 +00:00
2020-08-12 00:31:53 +00:00
datasette install datasette-vega
2019-05-16 10:15:03 +00:00
2020-10-10 23:19:39 +00:00
If the latest packaged release of Datasette has not yet been made available through Homebrew, you can upgrade your Homebrew installation in-place using::
datasette install -U datasette
2020-05-04 19:31:13 +00:00
.. _installation_pip:
2018-06-28 03:59:58 +00:00
2020-08-11 22:52:41 +00:00
Using pip
---------
2018-06-28 03:59:58 +00:00
2020-08-11 22:52:41 +00:00
Datasette requires Python 3.6 or higher. Visit `InstallPython3.com <https://installpython3.com/> `__ for step-by-step installation guides for your operating system.
2018-06-28 03:59:58 +00:00
You can install Datasette and its dependencies using `` pip `` ::
pip install datasette
You can now run Datasette like so::
2020-05-04 19:35:28 +00:00
datasette
2018-10-27 17:34:31 +00:00
2020-08-12 00:10:12 +00:00
.. _installation_advanced:
2020-08-11 22:52:41 +00:00
Advanced installation options
=============================
2020-05-04 19:31:13 +00:00
.. _installation_pipx:
2020-08-11 22:52:41 +00:00
Using pipx
----------
2020-05-04 19:10:31 +00:00
`pipx <https://pipxproject.github.io/pipx/> `__ is a tool for installing Python software with all of its dependencies in an isolated environment, to ensure that they will not conflict with any other installed Python software.
If you use `Homebrew <https://brew.sh/> `__ on macOS you can install pipx like this::
brew install pipx
pipx ensurepath
Without Homebrew you can install it like so::
python3 -m pip install --user pipx
python3 -m pipx ensurepath
The `` pipx ensurepath `` command configures your shell to ensure it can find commands that have been installed by pipx - generally by making sure `` ~/.local/bin `` has been added to your `` PATH `` .
Once pipx is installed you can use it to install Datasette like this::
pipx install datasette
Then run `` datasette --version `` to confirm that it has been successfully installed.
2021-10-13 21:09:10 +00:00
Installing plugins using pipx
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can install additional datasette plugins with `` pipx inject `` like so::
$ pipx inject datasette datasette-json-html
injected package datasette-json-html into venv datasette
done! ✨ 🌟 ✨
$ datasette plugins
[
{
"name": "datasette-json-html",
"static": false,
"templates": false,
"version": "0.6"
}
]
2020-05-04 19:10:31 +00:00
Upgrading packages using pipx
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can upgrade your pipx installation to the latest release of Datasette using `` pipx upgrade datasette `` ::
$ pipx upgrade datasette
upgraded package datasette from 0.39 to 0.40 (location: /Users/simon/.local/pipx/venvs/datasette)
To upgrade a plugin within the pipx environment use `` pipx runpip datasette install -U name-of-plugin `` - like this::
% datasette plugins
[
{
"name": "datasette-vega",
"static": true,
"templates": false,
"version": "0.6"
}
]
$ pipx runpip datasette install -U datasette-vega
Collecting datasette-vega
Downloading datasette_vega-0.6.2-py3-none-any.whl (1.8 MB)
|████████████████████████████████| 1.8 MB 2.0 MB/s
...
Installing collected packages: datasette-vega
Attempting uninstall: datasette-vega
Found existing installation: datasette-vega 0.6
Uninstalling datasette-vega-0.6:
Successfully uninstalled datasette-vega-0.6
Successfully installed datasette-vega-0.6.2
$ datasette plugins
[
{
"name": "datasette-vega",
"static": true,
"templates": false,
"version": "0.6.2"
}
]
2020-05-04 19:31:13 +00:00
.. _installation_docker:
Using Docker
------------
A Docker image containing the latest release of Datasette is published to Docker
Hub here: https://hub.docker.com/r/datasetteproject/datasette/
If you have Docker installed (for example with `Docker for Mac
<https://www.docker.com/docker-mac> `_ on OS X) you can download and run this
image like so::
docker run -p 8001:8001 -v `pwd` :/mnt \
datasetteproject/datasette \
datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db
This will start an instance of Datasette running on your machine's port 8001,
serving the `` fixtures.db `` file in your current directory.
Now visit http://127.0.0.1:8001/ to access Datasette.
(You can download a copy of `` fixtures.db `` from
https://latest.datasette.io/fixtures.db )
To upgrade to the most recent release of Datasette, run the following::
docker pull datasetteproject/datasette
2020-05-28 18:27:24 +00:00
Loading SpatiaLite
2020-05-04 19:31:13 +00:00
~~~~~~~~~~~~~~~~~~
The `` datasetteproject/datasette `` image includes a recent version of the
:ref: `SpatiaLite extension <spatialite>` for SQLite. To load and enable that
module, use the following command::
docker run -p 8001:8001 -v `pwd` :/mnt \
datasetteproject/datasette \
datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db \
2020-10-19 22:37:31 +00:00
--load-extension=spatialite
2020-05-04 19:31:13 +00:00
You can confirm that SpatiaLite is successfully loaded by visiting
http://127.0.0.1:8001/-/versions
Installing plugins
~~~~~~~~~~~~~~~~~~
If you want to install plugins into your local Datasette Docker image you can do
so using the following recipe. This will install the plugins and then save a
brand new local image called `` datasette-with-plugins `` ::
docker run datasetteproject/datasette \
pip install datasette-vega
docker commit $(docker ps -lq) datasette-with-plugins
You can now run the new custom image like so::
docker run -p 8001:8001 -v `pwd` :/mnt \
datasette-with-plugins \
datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db
You can confirm that the plugins are installed by visiting
http://127.0.0.1:8001/-/plugins
2021-05-24 18:14:45 +00:00
2021-05-24 18:15:15 +00:00
Some plugins such as `datasette-ripgrep <https://datasette.io/plugins/datasette-ripgrep> `__ may need additional system packages. You can install these by running `apt-get install` inside the container::
2021-05-24 18:14:45 +00:00
docker run datasette-057a0 bash -c '
apt-get update &&
apt-get install ripgrep &&
pip install datasette-ripgrep'
docker commit $(docker ps -lq) datasette-with-ripgrep