Skip to content

Installation Guide

This guide will walk you through installing MkDocs and the Material theme to create stunning documentation.

Prerequisites

Before you begin, ensure you have the following installed on your system:

  • Python 3.8+ - MkDocs requires Python 3.8 or higher
  • pip - Python package installer
  • Git (optional) - For version control

Python Installation

If you don't have Python installed:

  • Windows: Download from python.org
  • macOS: Use Homebrew: brew install python3
  • Linux: Use your package manager: sudo apt install python3 python3-pip

Installation Methods

Install MkDocs and Material theme using pip:

pip install mkdocs-material

This will install:

  • MkDocs (latest version)
  • Material for MkDocs theme
  • All required dependencies

For a complete installation with all optional dependencies:

pip install mkdocs-material[imaging]

This includes additional packages for:

  • Social card generation
  • Image optimization
  • Enhanced features

For isolated installation using pipx:

pipx install mkdocs-material

Info

pipx installs Python applications in isolated environments

Using the official Docker image:

docker pull squidfunk/mkdocs-material

Run with:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Installing Additional Plugins

For the complete experience shown in this documentation, install these additional packages:

# Essential plugins
pip install mkdocs-jupyter               # Jupyter notebook support
pip install mkdocstrings[python]         # API documentation
pip install mkdocs-git-revision-date-localized-plugin  # Git revision dates
pip install mkdocs-minify-plugin         # Minification
pip install mkdocs-redirects             # Redirects
pip install mkdocs-awesome-pages-plugin  # Enhanced navigation
pip install mike                         # Versioning

# Additional dependencies for notebooks
pip install jupytext                     # .py notebook support
pip install notebook                     # Notebook execution
pip install ipywidgets                   # Interactive widgets

Verify Installation

After installation, verify everything is working:

# Check MkDocs version
mkdocs --version

# Check Material theme
python -c "import material; print(material.__version__)"

# Create a test project
mkdocs new test-project
cd test-project

# Add Material theme to mkdocs.yml
echo "theme:" >> mkdocs.yml
echo "  name: material" >> mkdocs.yml

# Serve the test site
mkdocs serve

Visit http://127.0.0.1:8000 to see your site!

Troubleshooting

Common Issues

Permission Denied

If you get permission errors during installation:

pip install --user mkdocs-material

Or use a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mkdocs-material
Module Not Found

If Python can't find installed packages:

  1. Check your Python path: which python
  2. Ensure pip matches Python: which pip
  3. Try using python -m pip instead of pip
Version Conflicts

If you encounter dependency conflicts:

# Create a fresh virtual environment
python -m venv fresh-env
source fresh-env/bin/activate
pip install --upgrade pip
pip install mkdocs-material

Platform-Specific Notes

  • Use PowerShell or Command Prompt as Administrator
  • Replace / with \ in file paths
  • Use python instead of python3
  • May need to use pip3 instead of pip
  • Install Xcode Command Line Tools if needed
  • Consider using Homebrew for Python management
  • May need sudo for system-wide installation
  • Use virtual environments to avoid conflicts
  • Install python3-venv if not available

Next Steps

🎉 Congratulations! You've successfully installed MkDocs Material.

Now you're ready to:

Need Help?