blackjack-gui
Single-player blackjack including graphical and command line interfaces, written in Python. Can be used to simulate games and to practise basic strategy and card counting.
Installation
blackjack-gui requires Python 3.10 or newer and uses tkinter. Make sure it's installed in your system:
$ sudo apt install python3-tk
or similar (otherwise, you'll see ModuleNotFoundError: No module named 'tkinter').
Then:
$ python3 -m venv venv
$ source venv/bin/activate
$ pip3 install blackjack-gui
Usage
blackjack [-h] [--cli] [--ai] [--count] [--bet BET] [--stack STACK]
[--n-games N_GAMES] [--loglevel LOGLEVEL] [--cards CARDS]
[--dealer-cards DEALER_CARDS] [--subset {hard,soft,pairs,hard/soft,soft/pairs}]
[--rules {US,Helsinki}]
Options
| Name | Default | Description |
|---|---|---|
--cli |
False |
Use command line version. |
--ai |
False |
If True, computer plays instead of you. Only with --cli. |
--count |
False |
If True, ai uses card counting. Only with --cli and --ai. The bet spread: 1 unit (true count<1), 2 units (TC=1), 3 units (TC=3), 4 units (TC=4), 8 units (TC=5), 12 units (TC>=6). |
--bet |
10 | Bet size (max 100). |
--stack |
200 | Initial stack. |
--n-games |
10 | Number of rounds to be played. Only with --cli. |
--loglevel |
DEBUG |
Adjust amount of logging: DEBUG or INFO. Only with --cli. |
--cards |
Determine the first player cards, e.g. --cards=A,8,K. Shuffles the shoe after every hand. Multiple options (one will be randomly selected) can be defined like this: "A,7;9,9;10,2". |
|
--subset |
Instead of --cards, practice with one of the subsets: hard, soft, pairs, hard/soft, or soft/pairs |
|
--dealer-cards |
Determine the first dealer cards. Useful for testing. | |
--rules |
US |
Rules to be used. Can be Helsinki or US. See the basic strategy charts below. |
Examples
Open the GUI version with Casino Helsinki Rules:
$ blackjack
With US rules:
$ blackjack --rules US
With the default settings, play 10 rounds of blackjack with the command line interface:
$ blackjack --cli
Let the computer play perfect basic game and use card counting technique to bring down the house:
$ blackjack --cli --ai --count --n-games=100000 --loglevel=INFO
Simulate soft 19 starting hand only:
$ blackjack --cli --ai --n-games=10000 --loglevel=INFO --cards=A,8
Practise to play "hard" starting hands:
$ blackjack --subset hard
Rules
Blackjack rules vary depending on the casino. In this application they follow the rules of Casino Helsinki, explained in Finnish here, i.e.:
- 6 decks
- Blackjack pays 3 to 2
- Dealer must stand on soft 17
- Dealer peek is not in use
- Any two cards can be doubled
- Max. 4 hands can be achieved by splitting
- Doubling after splitting is allowed
- Aces can be split but they receive only one extra card
- Resplit of aces is allowed
- Early surrender is allowed but not against Ace
- A 7-7-7 with the first three cards (not in a split game) pays 3 to 1 directly
See overview of the most common rule variations here.
Optimal basic strategy for Casino Helsinki
- Note that 16 vs 10 with 3 or more cards = Stay
- 7,7 would be normally Surrender, but not in Helsinki because of the 7-7-7 rule
Optimal basic strategy for a typical U.S. casino
The rules in the U.S. typically include:
- Dealer must hit on soft 17
- Dealer peek is in use
- Late surrender is not available
- Re-splitting of Aces (RSA) is not available
- Doubling and splitting rules otherwise same as above
- 7-7-7 rule is not available
Rule-based deviations
There are a few deviations from the basic strategy, which depend on the specific combination of the table rules. For a detailed, rule-specific strategy, consult the Wizard of Odds Blackjack Strategy Calculator to identify the optimal basic strategy for each game configuration.
Count-based deviations
Card counting affects the basic strategy. The following deviations are implemented
in blackjack-gui (I will slowly add more). Use "Coach mode" with "Include deviations" to verify your play!
| Your Hand | Dealer's Upcard | Basic strategy | Deviation | Index |
|---|---|---|---|---|
| 2-10 | A | Don't take insurance | Take | +3 |
| A | A | Don't take even money | Take | +3 |
| 16 | 10 | Hit | Stand | 0+ |
| 12 | 2 | Hit | Stand | +3 |
| 12 | 3 | Hit | Stand | +2 |
| 12 | 4 | Stand | Hit | 0- |
| A,4 | 4 | Double | Hit | 0- |
Where 0- means any negative running count, 0+ means any positive running count, and +X means true count of X or greater.
Development
Install blackjack-gui with dev-dependencies from GitHub:
git clone https://github.com/tukiains/blackjack-gui
cd blackjack-gui/
python3 -m venv venv
source venv/bin/activate
pip3 install --upgrade pip
pip3 install .[dev,test]
pre-commit install
Run unit and integration tests:
pytest tests/unit.py
pytest tests/integration.py
Run pre-commit checks:
pre-commit run --all
Credits
- Card images sourced from Google's Vector Playing Cards.
- Basic strategy follows Wizard of Odds Blackjack Strategy Calculator.
- Deviations are based on A1 Blackjack, an excellent source of free and useful blackjack content.
- Inspiration drawn from Blackjack Apprenticeship the premier resource for serious card counters.
Licence
MIT
1 maintainer
Release files for blackjack-gui 1.8.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| blackjack_gui-1.8.1.tar.gz | 5.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| blackjack_gui-1.8.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size:11.8 MB
Release files / blackjack_gui-1.8.1.tar.gz
| Download URL | blackjack_gui-1.8.1.tar.gz |
|---|---|
| Size | 5.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fa7e5695d1100e6e5a3b663b3ecbc24526878b51aa3534dbdea046e5c4c7978a
|
|
BLAKE2b-256 checksum How to use checksums |
1c146b5196317bc15b4a4fa9c5d973a9aa11e01c5e8872089eb738bd19082f4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 18, 2025.
Transparency logRelease files / blackjack_gui-1.8.1-py3-none-any.whl
| Download URL | blackjack_gui-1.8.1-py3-none-any.whl |
|---|---|
| Size | 5.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e0a50d19a97da388aa1fda875a22f8c6dd8832d690dd79d7b15c83d6dc1bcf6f
|
|
BLAKE2b-256 checksum How to use checksums |
fb7bf494848c7907617cb3dc4b6ac4f1154e8585c7c0f5617628ac3f8368e769
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 18, 2025.
Transparency log
