{"id":"371258dc8f2a486d","repo":"sqlalchemy/sqlalchemy","slug":"psycopg2-version-2-7-or-higher-is-required","errorCode":null,"errorMessage":"psycopg2 version 2.7 or higher is required.","messagePattern":"psycopg2 version 2\\.7 or higher is required\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"lib/sqlalchemy/dialects/postgresql/psycopg2.py","lineNumber":674,"sourceCode":"            executemany_mode,\n            {\n                EXECUTEMANY_VALUES: [\"values_only\"],\n                EXECUTEMANY_VALUES_PLUS_BATCH: [\"values_plus_batch\"],\n            },\n            \"executemany_mode\",\n        )\n\n        self.executemany_batch_page_size = executemany_batch_page_size\n\n        if self.dbapi and hasattr(self.dbapi, \"__version__\"):\n            m = re.match(r\"(\\d+)\\.(\\d+)(?:\\.(\\d+))?\", self.dbapi.__version__)\n            if m:\n                self.psycopg2_version = tuple(\n                    int(x) for x in m.group(1, 2, 3) if x is not None\n                )\n\n            if self.psycopg2_version < (2, 7):\n                raise ImportError(\n                    \"psycopg2 version 2.7 or higher is required.\"\n                )\n\n    def initialize(self, connection):\n        super().initialize(connection)\n        self._has_native_hstore = (\n            self.use_native_hstore\n            and self._hstore_oids(connection.connection.dbapi_connection)\n            is not None\n        )\n\n        self.supports_sane_multi_rowcount = (\n            self.executemany_mode is not EXECUTEMANY_VALUES_PLUS_BATCH\n        )\n\n    @classmethod\n    def import_dbapi(cls):\n        import psycopg2","sourceCodeStart":656,"sourceCodeEnd":692,"githubUrl":"https://github.com/sqlalchemy/sqlalchemy/blob/d9b44cb731bd27e6e82c99a3c0fb598214e8e7ff/lib/sqlalchemy/dialects/postgresql/psycopg2.py#L656-L692","documentation":"Raised during psycopg2 dialect initialization when the installed psycopg2 DBAPI reports a version older than 2.7. SQLAlchemy's psycopg2 dialect relies on APIs (such as fast execution helpers and certain cursor features) introduced in psycopg2 2.7, so older versions are rejected outright. The version is parsed from dbapi.__version__ via regex, and an ImportError is raised to halt engine creation immediately. This is a hard version floor enforced at dialect construction time.","triggerScenarios":"Calling create_engine(\"postgresql+psycopg2://...\") in an environment where pip/import resolves to psycopg2 < 2.7 (e.g. system packages, pinned old requirements, a stale virtualenv, or a conflicting psycopg2-binary install). The check fires once dbapi is imported and __version__ is parsed.","commonSituations":"CI/containers or production images that ship an old psycopg2 from OS package managers. Downgrading psycopg2 accidentally via a conflicting transitive dependency. Local virtualenvs created long ago and never refreshed. Docker images based on older distro releases.","solutions":["Upgrade psycopg2: run `pip install -U 'psycopg2>=2.7'` (or psycopg2-binary for quick local installs).","Pin a modern version in requirements.txt/pyproject.toml, e.g. psycopg2-binary>=2.9.","Recreate/refresh the virtualenv or rebuild the Docker image so the new wheel is picked up.","Verify with `python -c \"import psycopg2; print(psycopg2.__version__)\"` that the correct version is now imported."],"exampleFix":"// before (requirements.txt)\npsycopg2==2.6.2\n\n// after\npsycopg2>=2.9,<3\n# or for local dev without a compiler:\npsycopg2-binary>=2.9,<3","handlingStrategy":"validation","validationCode":"import re\ntry:\n    import psycopg2\nexcept ImportError as e:\n    raise RuntimeError(\"psycopg2 is not installed; pip install psycopg2-binary\") from e\nm = re.match(r\"(\\d+)\\.(\\d+)\", psycopg2.__version__)\nver = tuple(int(x) for x in m.groups()) if m else (0, 0)\nif ver < (2, 7):\n    raise RuntimeError(\n        f\"psycopg2 {psycopg2.__version__} is too old; version >= 2.7 required.\"\n    )\n# now safe to create_engine(\"postgresql+psycopg2://...\")","typeGuard":null,"tryCatchPattern":"try:\n    engine = create_engine(\"postgresql+psycopg2://user:pw@host/db\")\nexcept ImportError as e:\n    if \"psycopg2 version 2.7\" in str(e):\n        # upgrade the driver, then retry app startup\n        raise RuntimeError(\"Run: pip install -U 'psycopg2-binary>=2.7'\") from e\n    raise","preventionTips":["Pin psycopg2 (or psycopg2-binary) >= 2.7 in requirements.txt / pyproject.toml.","Check psycopg2.__version__ at application startup, before creating any engine.","Prefer the modern 'psycopg' (v3) driver for new projects to avoid this legacy constraint."],"tags":["sqlalchemy","psycopg2","postgresql","version-mismatch","dependency"],"analyzedSha":"d9b44cb731bd27e6e82c99a3c0fb598214e8e7ff","analyzedAt":"2026-08-01T17:20:52.075Z","schemaVersion":2}