Install & Compatibility
Where this runs
tested against v4.2.1 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.152s · 195.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 10.8s · import 2.000s · 186MB
195MB installed
● package 195MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
upsert
✓ from pangres import upsert
✗ import pangres
While 'import pangres; pangres.upsert(...)' works, direct import is preferred.
aupsert
✓ from pangres import aupsert
Async upsert function introduced in v4.1.
Inserts or updates rows in PostgreSQL using a DataFrame with a primary key index. The engine can be replaced with a connection for transaction control.
import pandas as pd
from sqlalchemy import create_engine
from pangres import upsert
engine = create_engine('postgresql://user:pass@localhost/db')
df = pd.DataFrame({'id': [1, 2], 'value': ['a', 'b']}).set_index('id')
upsert(con=engine, df=df, table_name='my_table', if_row_exists='update')
Errors
Common errors & fixes
AttributeError: module 'pangres' has no attribute 'upsert'
After 'import pangres', the upsert function is not directly accessible as a module attribute in older versions or due to missing exports.
fixUse 'from pangres import upsert' or upgrade to v4.2.1 where exports are fixed.
sqlalchemy.exc.InvalidRequestError: A value is required for a bound parameter in the WHERE clause
Pangres requires the DataFrame index to be named (as a column in the database). An unnamed index or MultiIndex with duplicate level names causes this.
fixEnsure the DataFrame index has a name (e.g., df.index.name = 'id'). For MultiIndex, ensure all level names are unique and match the database primary key columns.
Upgrade
Version history
4.2.1latest on PyPI · released Nov 5, 2023
Audit
Dependencies
pandasrequiredUpsert operations require DataFrames
sqlalchemyrequiredDatabase connection and operations
alembicrequiredRequired for SQLAlchemy >= 2.0 compatibility (>=1.7.2)
packagingrequiredDependency added in v4.2.0 for version parsing
psycopg2optionalRecommended for PostgreSQL connections
asyncpgoptionalRequired for async PostgreSQL support
aiosqliteoptionalRequired for async SQLite support
aiomysqloptionalRequired for async MySQL support