---
title: "Installation"
guide-section: "Getting Started"
tags: [Getting Started, Setup]
---

# Installation

This guide covers how to install Great Docs and its prerequisites.

## Prerequisites

Before installing Great Docs, ensure you have:

- **Python 3.11 or later**
- **Quarto** – The publishing system that renders your documentation

### Installing Quarto

Great Docs uses Quarto to render documentation. Install it from
[quarto.org](https://quarto.org/docs/get-started/):

::: {.panel-tabset}

## macOS

```{.bash filename="Terminal"}
# Using Homebrew
brew install quarto

# Or download the installer from quarto.org
```

::: {.details summary="SVG generation is not working"}
Please confirm the successful import via

```{.python filename="Python"}
import cairosvg
```

If `cairosvg` is installed but the required libraries still cannot be found, add the brew dynamic
library to your terminal environment by running:

```{.bash filename="Terminal"}
echo 'export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_FALLBACK_LIBRARY_PATH"' >> ~/.zshrc
```

:::

## Linux

```{.bash filename="Terminal"}
# Download and install the .deb package (Ubuntu/Debian)
# Get the latest release URL from https://quarto.org/docs/get-started/
wget <quarto-release-url>.deb
sudo dpkg -i <quarto-release-filename>.deb

# Or use your package manager
```

## Windows

Download and run the installer from [quarto.org](https://quarto.org/docs/get-started/).

:::

Verify the installation:

```{.bash filename="Terminal"}
quarto --version
```

## Installing Great Docs

### From PyPI

The simplest way to install Great Docs:

```{.bash filename="Terminal"}
pip install great-docs
```

### From GitHub

Install the latest development version directly from GitHub:

```{.bash filename="Terminal"}
pip install git+https://github.com/posit-dev/great-docs.git
```

Or install a specific version:

```{.bash filename="Terminal"}
# Install from a specific branch
pip install git+https://github.com/posit-dev/great-docs.git@main

# Install from a specific tag
pip install git+https://github.com/posit-dev/great-docs.git@v0.1.0
```

### Development Installation

For contributing to Great Docs or testing the latest features:

```{.bash filename="Terminal"}
# Clone the repository
git clone https://github.com/posit-dev/great-docs.git
cd great-docs

# Install in editable mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"
```

## Verify Installation

After installation, verify everything is working:

```{.bash filename="Terminal"}
# Check Great Docs version
great-docs --help

# Check Quarto version
quarto --version
```

You should see the Great Docs help message and the Quarto version number.

## Upgrading Great Docs

When a new version of Great Docs is released, upgrade using the same tool you used to install it:

::: {.panel-tabset}

## pip

```{.bash filename="Terminal"}
pip install --upgrade great-docs
```

## uv

```{.bash filename="Terminal"}
uv pip install --upgrade great-docs
```

If Great Docs is declared in your `pyproject.toml` dependencies, update the version constraint there
and run `uv sync` instead.

## pipx

```{.bash filename="Terminal"}
pipx upgrade great-docs
```

:::

### After upgrading

1. **Verify the new version**

   ```{.bash filename="Terminal"}
   great-docs --version
   ```

2. **Review the changelog** — Check the
   [release notes](https://github.com/posit-dev/great-docs/releases) for breaking changes,
   new configuration options, or deprecated features that may affect your site.

3. **Rebuild your site** — Run `great-docs build` to pick up any changes in the build pipeline,
   templates, or default configuration.

::: {.callout-tip}
You do **not** need to re-execute user guide notebooks after upgrading. A plain `great-docs build`
is sufficient as it regenerates reference pages and templates without re-running notebook code
(which can be time-consuming).
:::

## Next Steps

With Great Docs and Quarto installed, you're ready to generate your first documentation site.

- [Quick Start](quickstart.qmd) walks you through `great-docs init` and `great-docs build`
- [Configuration](configuration.qmd) covers customizing behavior through `great-docs.yml`
