# Get started

Zensical is a modern static site generator designed to simplify building and maintaining project documentation. It's built by the creators of [Material for MkDocs](<https://squidfunk.github.io/mkdocs-material/>) and shares the same core design principles and philosophy – batteries included, easy to use, with powerful customization options.

*Already using MkDocs or Material for MkDocs? [See how to migrate an existing project gradually](<https://zensical.org/docs/compatibility/mkdocs/migration/index.md>).*

## Installation

Zensical is written in Rust and Python, and is published as a [Python package](<https://pypi.org/project/zensical>). We recommend to use a Python *virtual environment* when installing [with `pip`](<#install-with-pip>) or [with `uv`](<#install-with-uv>). Both options automatically install all necessary dependencies alongside Zensical.

> [!NOTE]
>
> **Prerequisites**
>
> You need to have Python and a Python package manager installed on your system before you install Zensical. We recommend you follow the [Python Setup and Usage](<https://docs.python.org/3/using>) instructions for your operating system provided on the [Python website](<https://www.python.org/>). Modern Python distributions include the `pip` package manager, so unless you are developing Python software and use `uv`, this is the simplest option to install Zensical on your system.

> [!TIP]
>
> **Use with Docker**
>
> If you want to run Zensical in a container for previews and builds, you can use our [official Docker image](<https://hub.docker.com/r/zensical/zensical>). Note that it's not intended for hosting the site. For installation and usage instructions, see the documentation on Docker Hub.

### Install with pip

Zensical can be installed into a virtual environment[^/docs/get-started/#venv] with `pip`.

Open up a terminal window and install Zensical by first setting up a virtual environment and then using `pip` to install the Zensical package into it:

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install zensical
```

Open up a Command Window and install Zensical by first setting up a virtual environment and then using `pip` to install the Zensical package into it:

```ps1
python -m venv .venv  # (1)!
.venv\Scripts\activate
pip install zensical
```

1. Depending on your Python installation, you may need to use a different binary name such as `python3` or use `py -3`.

Open up a terminal window and install Zensical by first setting up a virtual environment and then using `pip` to install the Zensical package into it:

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install zensical
```

### Install with uv

If you are developing software using Python, chances are you're already using [`uv`](<https://docs.astral.sh/uv/>) as a package and project manager, which has become popular in recent years.

To install Zensical with `uv` and add it to your development dependencies in your `pyproject.toml`, use:

```sh
uv init
uv add --dev zensical
uv run zensical
```

Note that when using Zensical as a project dependency, you need to always either use `uv run` or activate the project's virtual environment manually.

> [!TIP]
>
> **Running as a `uv` tool**
>
> We recommend always running Zensical from a project virtual environment to make sure the version used is well defined. However, `uv` can also run Zensical as a tool with a one-liner. See the [`uv` documentation](<https://docs.astral.sh/uv/concepts/tools/#tool-environments>) for details.

> [!WARNING]
>
> **Symlink mode**
>
> Zensical doesn't support [uv's symlink mode](<https://docs.astral.sh/uv/reference/settings/#link-mode>) for package installation. We are working on lifting this limitation by changing how themes and their assets are packaged and distributed. Follow progress in these backlog items:
>
> - [https://github.com/zensical/backlog/issues/137](<https://github.com/zensical/backlog/issues/137>)
> - [https://github.com/zensical/backlog/issues/151](<https://github.com/zensical/backlog/issues/151>)

## Third-party distributions

There are other distributions that make Zensical available but they may or may not use the official packages we distribute exclusively through PyPI. You can use these distributions if you have good reasons to do so but for normal use we recommend the installation methods above that we officially support.

### Install with conda/Mamba

Zensical is available in the [conda-forge](<https://conda-forge.org/>) community repository so that it can be installed using [conda](<https://docs.conda.io/en/latest/>) or [Mamba](<https://mamba.readthedocs.io>).

> [!WARNING]
>
> We cannot provide support for distributions we do not control. If you experience any issues please contact the maintainers of [conda-forge/zensical-feedstock](<https://github.com/conda-forge/zensical-feedstock>).

```text
conda create -n zensical python=3.14
conda activate zensical
conda install -c conda-forge zensical
```

If you are using conda or Mamba, make sure that the base environment is activated. If you are using conda, you can just open an [Anaconda Prompt](<https://www.anaconda.com/docs/reference/glossary#anaconda-prompt>). If you installed Mamba as part of [Miniforge](<https://conda-forge.org/download/>), there will be an equivalent Miniforge Prompt.

```text
conda create -n zensical python=3.14
conda activate zensical
conda install -c conda-forge zensical
```

```text
conda create -n zensical python=3.14
conda activate zensical
conda install -c conda-forge zensical
```

[^/docs/get-started/#venv]: A [Python virtual environment](<https://docs.python.org/3/tutorial/venv.html>) is a folder in your project directory that contains its own copy of Python and any Python packages the project needs. By installing Zensical and its dependencies into a virtual environment you ensure that it does not interfere with other projects on your computer that also use Python.