pySim: a Python shell for reading and programming SIM cards

One shell replaces the old batch tools

pySim is a collection of Python programs for working with subscriber identity modules of cellular networks, covering SIM, UICC, USIM, ISIM, HPSIM and eUICCs. The catalogue is worth reading because it shows the division of labour. pySim-shell.py is the interactive tool, used to explore, read and decode the contents of any supported card model or card application, and, if you hold the credentials such as the ADM PIN, to write to the card and edit its contents. pySim-read.py and pySim-prog.py are described as legacy tools for batch programming common parameters across a batch of programmable cards. The README is direct about this: much of what is online still describes the legacy tools, but they have been superseded by the more capable pySim-shell, and users are strongly encouraged to move over unless they have a very specific need such as batch programming large quantities of cards, which the README calls about the only remaining use case for them.

Writable files need a programmable card

The most important paragraph in the README is the caveat about access control. The access control configuration of normal production cards issued by operators restricts significantly which files a normal user can read, and particularly which files they can write, so the full functionality of pySim can only be used with programmable SIM, USIM, ISIM and HPSIM cards, with the sysmocom programmable card products given as an example. Those cards are special in a specific way, since they come with the kind of keys that allow you to write the fields that normally only an operator can program. The stated reason to care is running your own cellular network and configuring your own cards for it. That framing keeps pySim on the right side of a line. It is an operator side tool for cards you own, and the reason the keys exist is that a self hosted network needs subscriber identities the commercial operator would otherwise issue.

The dependency list is the real setup guide

Installation is a dependency install, and the README lists the packages plainly: bidict, cmd2 at 1.5.0 or newer, colorlog, construct at 2.9.51 or newer, pyosmocom, jsonpath-ng, packaging, pycryptodomex, pyscard, pyserial, pytlv, pyyaml at 5.4 or newer, smpp.pdu from the hologram-io repository, and termcolor. The setup.py in the repository states tighter versions than the README, with cmd2 at 2.6.2 and below 4.0, construct at 2.10.70 or newer, pyosmocom at 0.0.12 or newer, and it adds asn1tools and smpp.twisted3 from git URLs. The setup.py also defines two extras, one for the smdpp tool with klein, service-identity, pyopenssl, requests and smplib, and one called CardKeyProviderPgsql for PostgreSQL key storage, plus package data for the ASN.1 definitions of the eSIM remote provisioning protocols under pySim.esim.

Installing on Debian and Arch

The Debian example installs the card reader stack and the Python pieces through apt, then the rest through pip:

sudo apt-get install --no-install-recommends \
	pcscd libpcsclite-dev \
	python3 \
	python3-setuptools \
	python3-pycryptodome \
	python3-pyscard \
	python3-pip

pip3 install --user -r requirements.txt

The pcscd and libpcsclite-dev packages are the smart card reader daemon and its development headers, which is how the tool reaches a physical card. After the dependencies are in place, the applications can be started directly from the cloned repository. Arch users have a package in the AUR named python-pysim-git, installed with an AUR helper:

# Install
yay -Sy python-pysim-git

# Uninstall
sudo pacman -Rs python-pysim-git

The upstream repository is the Osmocom one on Gitea, and the README gives the clone command:

git clone https://gitea.osmocom.org/sim-card/pysim.git

pySim-trace needs a packet decoder alongside it

One tool has extra requirements. pySim-trace.py is for an in-depth decode of SIM card protocol traces, of the kind obtained from Osmocom SIMtrace2 or osmo-qcdiag, and it needs tshark and the pyshark Python package in addition to the common dependencies. The README warns that the tshark package in Debian versions before 11 may not work with pyshark, which is the sort of detail that saves an afternoon of blank output. The value of the tool is that it turns a captured trace into a readable dialogue, which is what you need when you are debugging an APDU exchange rather than just reading files. The repository also carries pySim-smpp2sim.py, which is not described in the README beyond its name, and a contrib/ directory with further tools.

eUICC and the proof-of-concept SM-DP+

The eUICC side of the project is worth separating out. The setup.py packages list includes pySim.esim and pySim.esim.saip, along with pySim.global_platform and pySim.apdu_source, and the package data includes ASN.1 files for the response and the secure authentication protocol. On top of that sits osmo-smdpp.py, described as a proof-of-concept GSMA SGP.22 Consumer eSIM SM-DP+, which is the server side of remote eSIM provisioning. The proof-of-concept label matters if you plan to use it for anything real, since a consumer SM-DP+ deals with activation codes and profile installation, and a research implementation is not the same as a production grade service. The repository also has a smdpp-data/ directory, and the extra dependencies for that tool are installed separately, so it is an optional piece rather than part of the core shell.

Documentation, review process and where the code lives

The project is developed in the open on Osmocom's own infrastructure rather than on GitHub, and this repository is a mirror. The homepage at osmocom.org hosts the wiki with usage instructions, the manual and examples, and the user manual can be built from the source with sphinx using the Makefile in the docs directory. A pre-rendered HTML manual of the current master is published on the Osmocom downloads server along with a PDF version, and there is a slightly dated video presentation of pySim-shell. Contribution follows the Osmocom coding standards and a gerrit based patch review process, with the issue tracker on the Osmocom project page. There is no separate mailing list for the project, so discussions happen on the simtrace list, with the Osmocom mailing list rules applying. The licence is GPL-2.0, the repository has no GitHub releases, and the last push was on 2026-10-09.

Editorial conclusion

Adopt pySim if you run your own cellular network, you need to provision your own subscriber cards, or you are doing SIM card research with hardware you control, and you have a card reader and a programmable card. Do not expect it to work against cards issued by a commercial operator, because the README states that access control on production cards restricts which files can be read and written. Verify first that your reader is visible to pyscard, that the card you have is one of the programmable models, and that you install the dependencies the tool needs, since pySim-trace in particular requires tshark and pyshark, and pyshark is known not to work with Debian releases before 11.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. osmocom/pysim on GitHub
4. Project website
5. README