Skip to content

Installation

Prerequisites

  • Python 3.10 or newer

  • See Python installation for platform-specific instructions.

  • tkinter (optional, only required for the GUI sample application)

  • Part of the Python standard library, but may require extra steps to install on some platforms. See Tkinter installation for details.

  • pip (optional, required only for pip-based installation)

  • Comes with Python and is recommended for most users.

  • Poetry (optional, required only for Poetry-based installation)

  • Recommended for contributors and for developers who use Poetry in their own projects. See Poetry installation instructions for how to install Poetry itself. > Note: You must have at least one of pip or poetry installed to install dcmspec.

Sample Application Users

  • Install from PyPI (recommended for all sample applications, CLI and GUI)
pip install "dcmspec[gui]"

If you get an error about tkinter, see Tkinter installation.

  • Run CLI applications
<command> --help

Where <command> is one of the available CLI scripts, e.g.:

iodattributes --help
tdwiimoddefinition --help

Alternatively, you can use:

python -m dcmspec.apps.cli.<script_name> --help

See the CLI Applications for available commands and usage examples.

  • Run the GUI application
iod-explorer

See the UI Applications for more information.

API Users

Tip: If you use Poetry to manage your own project, you can skip the pip instructions below and go directly to Using Poetry.

See Dependencies and Optional Features below for details on core vs extra dependencies versions.

Using pip

  • Install core (lightweight) version from PyPI
pip install dcmspec
  • Install with PDF/table extraction support
pip install "dcmspec[pdf]"
  • Install with GUI support
pip install "dcmspec[gui]"
  • Install with both PDF and GUI support
pip install "dcmspec[gui,pdf]"
  • (Optional) To use the latest development version from GitHub
pip install "git+https://github.com/dwikler/dcmspec.git@main"

Using Poetry

  • Add to your Poetry project

If you are using Poetry to manage your own project, add dcmspec as a dependency with the desired optional features:

poetry add dcmspec              # core only
poetry add "dcmspec[gui]"       # with GUI support
poetry add "dcmspec[pdf]"       # with PDF support
poetry add "dcmspec[gui,pdf]"   # with both
  • (Optional) To use the latest development version from GitHub
poetry add "dcmspec@git+https://github.com/dwikler/dcmspec.git"

Import and use the API

from dcmspec.spec_model import SpecModel
# ... your code here ...

Contributors

For contributor installation and development instructions, see the CONTRIBUTING.md on GitHub.

Dependencies and Optional Features

  • Core Dependencies

The core dcmspec library is designed to be lightweight and only requires a minimal set of dependencies for parsing and working with DICOM specification tables in HTML/XHTML format.

Core dependencies include:

  • anytree
  • platformdirs
  • unidecode
  • bs4 (BeautifulSoup)
  • requests
  • lxml
  • rich

These are sufficient for most use cases, including all parsing and tree-building from DICOM standard HTML/XHTML documents.

Note on lxml: > lxml is a core dependency for fast and robust XML/HTML parsing. It is not a pure Python package, but pre-built wheels are available for most platforms. On some Linux systems, you may need to install system packages (e.g., libxml2-dev, libxslt-dev, and python3-dev) before installing lxml. See the lxml installation docs for details.

  • Optional PDF/Table Extraction Dependencies

Some features, such as extracting tables directly from PDF files, require additional heavy dependencies. These are not installed by default and are grouped under the pdf optional dependency.

To install with PDF/table extraction support from PyPI:

Using pip:

pip install "dcmspec[pdf]"

Or, for the latest development version from GitHub:

pip install "git+https://github.com/dwikler/dcmspec.git@main#egg=dcmspec[pdf]"

Or, using Poetry:

poetry add "dcmspec[pdf]"

Or, for the latest development version from GitHub:

poetry add "dcmspec[pdf]"@git+https://github.com/dwikler/dcmspec.git

Optional dependencies for PDF/table extraction:

  • pdfplumber
  • camelot-py
  • pandas
  • openpyxl
  • opencv-python-headless

These are only needed if you want to extract tables from PDF documents.

  • GUI Dependencies

If you want to use the sample GUI explorer app, you can install the gui extra:

Using pip from PyPI:

pip install "dcmspec[gui]"

Or, with Poetry from PyPI:

poetry add "dcmspec[gui]"

Or, for the latest development version from GitHub:

poetry add "dcmspec[gui]"@git+https://github.com/dwikler/dcmspec.git

This will install:

  • tkhtmlview

  • Summary

  • Default install: Lightweight, core parsing features only.

  • With [pdf] extra: Adds PDF/table extraction support.
  • With [gui] extra: Adds GUI dependencies for the sample explorer app.
  • You can combine extras, e.g., pip install "dcmspec[gui,pdf]". See the pyproject.toml for the full list of dependencies and extras.

See the API Reference for details on available classes.

Python Installation

  • You can check your version with: 
    python3 --version
  • On macOS, you can install Python with Homebrew or from python.org.
  • On Linux, use your system package manager (e.g., sudo apt install python3).
  • On Windows, use the python.org installer.

Tkinter Installation

tkinter is the Python interface to the Tcl/Tk GUI toolkit. On some platforms, installing tkinter will also install the required tcl-tk libraries.

  • macOS (Homebrew Python):

  • Install Python if not present yet. (Commands below are for Python 3.9, replace 3.9 with your Python version if needed). 

    brew install python@3.9

  • Then, install tkinter support: 
    brew install python-tk@3.9

  • For Python 3.10, 3.11, 3.12, use the matching python-tk@<version> formula, e.g.: 

    brew install python-tk@3.12

  • Windows or macOS (python.org installer): tkinter is usually included by default.

  • Ubuntu/Debian: Install with sudo apt install python3-tk

After installation, you can test if tkinter is available by running:

python3 -m tkinter

If a small window appears, tkinter is working.

For more details, see the Homebrew Python and Tkinter documentation and the python-tk Homebrew formulae.

Poetry Installation

  • Install with pipx:

  • macOS (Homebrew): 

    brew install pipx
pipx ensurepath
pipx install poetry

  • Linux/Windows: 
    python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install poetry

  • Windows:

    1. Open "Command Prompt" or "PowerShell" as administrator.
    2. Run: 
      python -m pip install --user pipx
python -m pipx ensurepath
pipx install poetry
    3. Close and reopen your terminal to update your PATH.

  • For more details or troubleshooting, refer to the Poetry installation guide.