> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/markitdown/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Detailed installation instructions for MarkItDown across different environments

## Prerequisites

MarkItDown requires **Python 3.10 or higher**. Before installing, verify your Python version:

```bash theme={null}
python --version
```

<Warning>
  If you have Python 3.9 or earlier, you'll need to upgrade to use MarkItDown.
</Warning>

## Virtual environment setup

We strongly recommend using a virtual environment to avoid dependency conflicts with other Python projects.

<Tabs>
  <Tab title="Standard Python">
    Create and activate a virtual environment using Python's built-in `venv` module:

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      python -m venv .venv
      source .venv/bin/activate
      ```

      ```bash Windows (PowerShell) theme={null}
      python -m venv .venv
      .venv\Scripts\Activate.ps1
      ```

      ```bash Windows (Command Prompt) theme={null}
      python -m venv .venv
      .venv\Scripts\activate.bat
      ```
    </CodeGroup>

    When activated, your terminal prompt will show `(.venv)` at the beginning.

    <Tip>
      To deactivate the virtual environment later, simply run `deactivate`.
    </Tip>
  </Tab>

  <Tab title="uv">
    [uv](https://github.com/astral-sh/uv) is a fast Python package installer. Create a virtual environment with a specific Python version:

    ```bash theme={null}
    uv venv --python=3.12 .venv
    source .venv/bin/activate
    ```

    <Warning>
      When using `uv`, be sure to use `uv pip install` rather than just `pip install` to install packages in the virtual environment.
    </Warning>
  </Tab>

  <Tab title="Anaconda">
    If you're using Anaconda or Miniconda, create an environment with:

    ```bash theme={null}
    conda create -n markitdown python=3.12
    conda activate markitdown
    ```

    To deactivate later:

    ```bash theme={null}
    conda deactivate
    ```
  </Tab>
</Tabs>

## Basic installation

Once your virtual environment is activated, install MarkItDown.

### Install all features

For complete format support, install with all optional dependencies:

<CodeGroup>
  ```bash pip theme={null}
  pip install 'markitdown[all]'
  ```

  ```bash uv theme={null}
  uv pip install 'markitdown[all]'
  ```
</CodeGroup>

This installs support for:

* PDF files
* Word documents (.docx)
* PowerPoint presentations (.pptx)
* Excel spreadsheets (.xlsx, .xls)
* Outlook messages (.msg)
* Audio transcription
* YouTube transcripts
* Azure Document Intelligence
* And more

<Note>
  The `[all]` extra provides backward-compatible behavior with MarkItDown versions prior to 0.1.0.
</Note>

### Minimal installation

For a minimal installation with only core dependencies:

```bash theme={null}
pip install markitdown
```

This includes support for:

* HTML
* Plain text formats (CSV, JSON, XML)
* Jupyter notebooks
* EPub files
* ZIP archives
* Basic image metadata (without OCR)

## Selective installation

Starting with version 0.1.0, MarkItDown organizes dependencies into optional feature groups. Install only what you need to keep your environment lean.

### Available feature groups

<AccordionGroup>
  <Accordion title="PDF support" icon="file-pdf">
    ```bash theme={null}
    pip install 'markitdown[pdf]'
    ```

    Dependencies:

    * `pdfminer.six` - Text extraction
    * `pdfplumber` - Table and layout detection
  </Accordion>

  <Accordion title="Office documents" icon="file-word">
    **Word documents:**

    ```bash theme={null}
    pip install 'markitdown[docx]'
    ```

    **PowerPoint presentations:**

    ```bash theme={null}
    pip install 'markitdown[pptx]'
    ```

    **Excel spreadsheets (modern):**

    ```bash theme={null}
    pip install 'markitdown[xlsx]'
    ```

    **Excel spreadsheets (legacy .xls):**

    ```bash theme={null}
    pip install 'markitdown[xls]'
    ```
  </Accordion>

  <Accordion title="Outlook messages" icon="envelope">
    ```bash theme={null}
    pip install 'markitdown[outlook]'
    ```

    Enables conversion of Outlook .msg files.
  </Accordion>

  <Accordion title="Audio transcription" icon="microphone">
    ```bash theme={null}
    pip install 'markitdown[audio-transcription]'
    ```

    Dependencies:

    * `pydub` - Audio processing
    * `SpeechRecognition` - Speech-to-text

    Supports .wav and .mp3 files.
  </Accordion>

  <Accordion title="YouTube transcripts" icon="youtube">
    ```bash theme={null}
    pip install 'markitdown[youtube-transcription]'
    ```

    Fetch transcripts from YouTube URLs.
  </Accordion>

  <Accordion title="Azure Document Intelligence" icon="microsoft">
    ```bash theme={null}
    pip install 'markitdown[az-doc-intel]'
    ```

    Dependencies:

    * `azure-ai-documentintelligence`
    * `azure-identity`

    Use Microsoft's cloud-based document processing service for superior accuracy.
  </Accordion>
</AccordionGroup>

### Combining feature groups

Install multiple feature groups by separating them with commas:

```bash theme={null}
pip install 'markitdown[pdf,docx,pptx]'
```

This installs only PDF, Word, and PowerPoint support.

<Tip>
  Start with a minimal installation and add features as needed to minimize dependencies.
</Tip>

## Install from source

For development or to use the latest unreleased features, install from the GitHub repository:

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/microsoft/markitdown.git
    cd markitdown
    ```
  </Step>

  <Step title="Install in development mode">
    ```bash theme={null}
    pip install -e 'packages/markitdown[all]'
    ```

    The `-e` flag installs in editable mode, so changes to the source code are immediately reflected.
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    markitdown --version
    ```
  </Step>
</Steps>

## Docker installation

Run MarkItDown in a Docker container for isolated environments:

<Steps>
  <Step title="Build the Docker image">
    ```bash theme={null}
    docker build -t markitdown:latest .
    ```
  </Step>

  <Step title="Run conversions">
    ```bash theme={null}
    docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
    ```

    The `--rm` flag automatically removes the container after it exits.
  </Step>
</Steps>

### Docker with volume mounting

For easier file access, mount a local directory:

```bash theme={null}
docker run --rm -v $(pwd):/data markitdown:latest /data/document.pdf > output.md
```

## Verify installation

Confirm MarkItDown is installed correctly:

```bash theme={null}
markitdown --version
```

You should see output like:

```
markitdown 0.1.0
```

### Test with a sample conversion

Create a simple HTML file and convert it:

```bash theme={null}
echo '<h1>Hello World</h1><p>This is a test.</p>' > test.html
markitdown test.html
```

Expected output:

```markdown theme={null}
# Hello World

This is a test.
```

## Optional dependencies

### ExifTool for image metadata

For enhanced image metadata extraction, install [ExifTool](https://exiftool.org/):

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install exiftool
    ```
  </Tab>

  <Tab title="Linux (Debian/Ubuntu)">
    ```bash theme={null}
    sudo apt-get install libimage-exiftool-perl
    ```
  </Tab>

  <Tab title="Windows">
    Download from [exiftool.org](https://exiftool.org/) and add to your PATH.
  </Tab>
</Tabs>

MarkItDown will automatically detect ExifTool if it's in your PATH.

### LLM integration

To use LLM-powered image descriptions, install an OpenAI-compatible client:

```bash theme={null}
pip install openai
```

Then use it in your code:

```python theme={null}
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("image.jpg")
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError for a specific format" icon="circle-exclamation">
    If you get an error like `MissingDependencyException` when converting a file, install the specific feature group:

    ```bash theme={null}
    pip install 'markitdown[pdf]'  # For PDF files
    pip install 'markitdown[docx]' # For Word documents
    # etc.
    ```
  </Accordion>

  <Accordion title="Permission denied errors" icon="lock">
    On Unix systems, if you encounter permission errors, avoid using `sudo`. Instead, ensure you're in a virtual environment:

    ```bash theme={null}
    python -m venv .venv
    source .venv/bin/activate
    pip install 'markitdown[all]'
    ```
  </Accordion>

  <Accordion title="Python version conflicts" icon="code-branch">
    If you have multiple Python versions installed, be explicit:

    ```bash theme={null}
    python3.12 -m venv .venv
    source .venv/bin/activate
    pip install 'markitdown[all]'
    ```
  </Accordion>

  <Accordion title="SSL certificate errors" icon="shield">
    If you encounter SSL errors when downloading packages:

    ```bash theme={null}
    pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org 'markitdown[all]'
    ```

    <Warning>
      Only use this as a last resort. SSL verification is important for security.
    </Warning>
  </Accordion>
</AccordionGroup>

## Upgrading

To upgrade to the latest version:

```bash theme={null}
pip install --upgrade 'markitdown[all]'
```

### Breaking changes in 0.1.0

If you're upgrading from version 0.0.1, be aware of these breaking changes:

<Warning>
  * Dependencies are now organized into optional feature groups. Use `pip install 'markitdown[all]'` for backward-compatible behavior.
  * `convert_stream()` now requires a binary file-like object (not text).
  * The `DocumentConverter` interface has changed to read from streams rather than file paths.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart guide" icon="rocket" href="/quickstart">
    Convert your first document with MarkItDown
  </Card>

  <Card title="Python API" icon="code" href="/api/markitdown">
    Explore the complete API reference
  </Card>

  <Card title="CLI reference" icon="terminal" href="/guides/cli-usage">
    Learn all command-line options
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/guides/plugins">
    Extend MarkItDown with custom converters
  </Card>
</CardGroup>