Registry / database / eralchemy

eralchemy

JSON →
library1.7.0pypypi✓ verified 25d ago

ERAlchemy is a Python library for generating Entity-Relation (ER) diagrams from SQLAlchemy models, declarative database metadata, or a simple text file format. It leverages the external Graphviz engine to visualize the relationships and can output diagrams in various formats such as PNG, SVG, and PDF. The current stable version is 1.6.0, with development activity having slowed in recent years, but it remains a functional tool for its primary purpose.

pip install eralchemy
INSTALL
IMPORT
SIG · ERALCHEMY
E
eralchemy
databasepythonv1.7.0
Install
3.3s avg
Import
879ms
Disk
41MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.919s · 43.2MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.3s · import 0.840s · 41MB
41MB installed
● package 41MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

render_er
from eralchemy import render_er

This quickstart demonstrates how to generate an ER diagram from SQLAlchemy models using `eralchemy`. It creates a simple SQLite database with two related tables (`User` and `Email`) and then uses `render_er` to generate a PNG file. Crucially, the external Graphviz program must be installed on your system for rendering to succeed.

from sqlalchemy import create_engine, Column, Integer, String, ForeignKey from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker, relationship from eralchemy import render_er import os # 1. Define SQLAlchemy models Base = declarative_base() class User(Base): __tablename__ = 'users' id = Column(Integer, primary_key=True) name = Column(String(50), nullable=False) emails = relationship('Email', back_populates='user') class Email(Base): __tablename__ = 'emails' id = Column(Integer, primary_key=True) address = Column(String(100), nullable=False, unique=True) user_id = Column(Integer, ForeignKey('users.id')) user = relationship('User', back_populates='emails') # 2. Create a dummy database and tables db_url = "sqlite:///./er_example.db" engine = create_engine(db_url) Base.metadata.create_all(engine) # 3. Generate the ER diagram output_file = "er_diagram.png" # IMPORTANT: Graphviz must be installed on your system for this to work. # Instructions for common OS: # - Debian/Ubuntu: sudo apt-get install graphviz # - macOS: brew install graphviz # - Windows: Download and install from graphviz.org, then add to PATH. try: render_er(db_url, output_file) print(f"ER diagram generated to {output_file}") print(f"To view it, ensure Graphviz is installed and open {output_file}") except Exception as e: print(f"Failed to generate ER diagram. Ensure Graphviz is correctly installed and in your system's PATH. Error: {e}") finally: # Clean up the dummy database file if it was created if os.path.exists("./er_example.db"): pass # os.remove("./er_example.db") # Uncomment to remove DB file after run
eralchemy --version
Debug
Known issues
gotchaERAlchemy fundamentally requires the Graphviz program to be installed on your system. It is not a Python package dependency handled by pip; you must install it separately according to your operating system's instructions (e.g., `apt-get install graphviz`, `brew install graphviz`). Without Graphviz, `render_er` will fail.
fix
Install Graphviz on your system and ensure its executables are available in your system's PATH. Refer to the official Graphviz documentation for detailed installation instructions.
affects: All versions
gotchaWhen installing `eralchemy[all]` to use `pygraphviz`, compilation issues can occur due to `pygraphviz`'s reliance on Graphviz's C libraries. This typically manifests as 'command 'gcc' failed' or similar errors during `pip install`.
fix
Ensure Graphviz and its development headers (e.g., `graphviz-dev` on Debian/Ubuntu, or Xcode Command Line Tools on macOS) are installed *before* attempting to install `pygraphviz` or `eralchemy[all]`. If issues persist, consider using the default rendering backend without `pygraphviz`.
affects: All versions
gotchaThe project's development activity has slowed, with fewer updates and new features compared to its earlier history. While functional for its core purpose, this might mean slower adoption of newer SQLAlchemy features or resolutions for niche compatibility issues.
fix
Be mindful of this if working with very new SQLAlchemy versions or complex model structures that push the boundaries of common ER diagram representations. Test thoroughly if encountering unexpected rendering issues.
affects: 1.x and later
gotchaERAlchemy might have limitations in accurately representing highly complex SQLAlchemy models, such as polymorphic inheritance, custom relationship types, or many-to-many relationships without explicit association tables. The generated diagrams might simplify or omit certain details.
fix
Verify the generated diagram against your actual model to ensure correctness. For highly complex cases, manual adjustments to the diagram or using an `eralchemy` 'meta' file for declarative definitions might be necessary to achieve the desired representation.
affects: All versions
Errors
Common errors & fixes
ValueError: Program dot not found in path.
ERAlchemy relies on Graphviz (specifically the `dot` executable) to render diagrams, but the `dot` program is not found in your system's PATH.
fix
Install Graphviz on your system. For Debian/Ubuntu: `sudo apt install graphviz libgraphviz-dev`. For macOS: `brew install graphviz`. For Windows, download and install Graphviz from their official website and ensure its `bin` directory is added to your system's PATH environment variable.
error: Microsoft Visual C++ 14.0 is required.
During the installation of `eralchemy` on Windows, its dependency `pygraphviz` attempts to compile, which requires Microsoft Visual C++ build tools.
fix
Install the 'Build Tools for Visual Studio' from Microsoft's website and ensure that the C++ build tools are selected during installation. Alternatively, install `eralchemy` using Anaconda/Conda via `conda install -c conda-forge eralchemy` which often handles these dependencies better on Windows.
Running eralchemy gives error on Win 10. Please install application. using "pip install application."
This error can occur due to missing or improperly installed database drivers or underlying issues with `pygraphviz`'s Windows installation, sometimes masked by a generic 'install application' message.
fix
Ensure Graphviz is properly installed and its `bin` directory is in the system PATH. For specific database drivers (e.g., Oracle, MySQL), ensure they are also correctly installed (e.g., `pip install cx_Oracle` or `pip install mysqlclient`). If issues persist on Windows, consider using Windows Subsystem for Linux (WSL) or a Docker environment.
eralchemy isn't compatible with the latest version of [SQLAlchemy]
The `eralchemy` library (version 1.6.0) has known incompatibilities with SQLAlchemy versions 1.4 and newer, which can lead to various runtime errors.
fix
Downgrade your SQLAlchemy installation to a version prior to 1.4 by running `pip install 'sqlalchemy<1.4'`.
Upgrade
Version history
1.7.0latest on PyPI · released May 5, 2026
Audit
Dependencies
GraphvizrequiredAn external system dependency required for rendering diagrams (e.g., PNG, SVG). Must be installed separately.
pygraphvizoptionalAn optional Python binding to Graphviz, offering an alternative rendering backend. Installed via `eralchemy[all]`.
Agent activity
22 hits · last 30 days
node
20
Resources
eralchemy — pip install eralchemy · libregistry