pyscard - Smartcard module for Python

2.3.1 verified Fri May 01 auth: no python

pyscard is a Python library for smart card communication using PC/SC API. It provides high-level wrappers for reading/writing to smart cards, monitoring card insertion/removal, and sending APDUs. Version 2.3.1 (October 2025) supports Python >=3.9 and SWIG 4.4. Active development with monthly releases.

pip install pyscard

Common errors

error ModuleNotFoundError: No module named 'smartcard' ↓

cause pyscard not installed.

fix

pip install pyscard

error smartcard.scard.SCardException: Cannot connect to smart card reader (0x80100001) ↓

cause PC/SC service not running or no reader connected.

fix

Start pcscd on Linux, ensure reader is plugged in, and check reader drivers on Windows/macOS.

error ImportError: libpcsc.so.1: cannot open shared object file: No such file or directory ↓

cause Missing PC/SC runtime library.

fix

Install libpcsclite1 on Debian/Ubuntu: sudo apt install libpcsclite1

error AttributeError: module 'smartcard' has no attribute 'CardRequest' ↓

cause Incorrect import path.

fix

Use from smartcard.CardRequest import CardRequest

Warnings

gotcha pyscard requires PC/SC service running. On Linux, ensure pcscd is installed and started (e.g., sudo systemctl start pcscd). ↓

fix Install and start pcscd: sudo apt install pcscd && sudo systemctl enable --now pcscd

deprecated Direct import of smartcard.scard functions like SCardEstablishContext is discouraged; use higher-level classes CardRequest and CardConnection. ↓

fix Use from smartcard.scard import SCardEstablishContext only if necessary; prefer CardRequest

breaking In 2.3.0, SCardListReaders() and SCardListReaderGroups() were fixed to use SCARD_AUTOALLOCATE. Code relying on manual memory management may break. ↓

fix Update code to not manually allocate buffers; let pyscard handle memory.

breaking In 2.3.0, connecting after releasing a connection raises an exception. Code that reuses a released connection will break. ↓

fix Create a new CardConnection or CardRequest after release.

Imports

CardRequest

wrong

from smartcard import CardRequest

correct

from smartcard.CardRequest import CardRequest

CardRequest is in a submodule, not directly in smartcard

CardConnection

wrong

import smartcard.CardConnection

correct

from smartcard.CardConnection import CardConnection

CardConnection is a class, not a module

SCardGetErrorMessage

wrong

from smartcard import SCardGetErrorMessage

correct

from smartcard.scard import SCardGetErrorMessage

SCard* functions are in scard submodule

Quickstart

Wait up to 5 seconds for a smart card, connect, retrieve and print the ATR.

import smartcard.util
from smartcard.CardRequest import CardRequest
from smartcard.CardConnection import CardConnection

def get_atr():
    request = CardRequest(timeout=5)
    card_service = request.waitforcard()
    card_service.connection.connect()
    atr = card_service.connection.getATR()
    print('ATR:', smartcard.util.toHexString(atr))
    card_service.connection.disconnect()

if __name__ == '__main__':
    get_atr()