Skip to main content

​
Installation Guide

This guide provides comprehensive installation instructions for Python Arcade Suite, including prerequisites, setup options, and troubleshooting common issues.

​
System Requirements

​
Required Software

Python

Version 3.9 or higherCheck your version:
python --version

pip

Latest version recommendedComes with Python, verify:
pip --version

Git

Any recent versionFor cloning the repository:
git --version

Web Browser

Chrome, Firefox, Safari, or EdgeModern browser with JavaScript enabled

​
Operating System Support

  • Linux: Full support (Ubuntu, Debian, Fedora, etc.)
  • macOS: Full support (10.14 or later)
  • Windows: Full support (Windows 10 or later)

​
Installation Methods

This is the recommended approach for most users.
1

Install Python

If you don’t have Python 3.9+ installed:On Ubuntu/Debian:
sudo apt update
sudo apt install python3 python3-pip
On macOS (using Homebrew):
brew install [email protected]
On Windows: Download from python.org and run the installer.
On Windows, make sure to check “Add Python to PATH” during installation!
2

Clone the Repository

Choose a directory for the project and clone it:
cd ~/projects  # or your preferred location
git clone https://github.com/YorberR/Python_Arcade.git
cd Python_Arcade
Don’t have Git? Download the ZIP file from GitHub and extract it.
3

Create a Virtual Environment (Optional but Recommended)

Virtual environments keep dependencies isolated:
# Create virtual environment
python -m venv venv

# Activate it
# On Linux/macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate
You’ll see (venv) in your terminal prompt when activated.
Using a virtual environment prevents conflicts with other Python projects on your system.
4

Install Dependencies

Install Streamlit and any other required packages:
pip install -r requirements.txt
The requirements.txt contains:
streamlit
Installation may take 1-2 minutes depending on your internet connection.
5

Verify Installation

Check that Streamlit is installed correctly:
streamlit --version
You should see output like:
Streamlit, version 1.x.x
6

Run the Application

Start the game suite:
streamlit run streamlit_app.py
The app should automatically open in your browser at http://localhost:8501.

​
Method 2: Quick Install (One-Liner)

For experienced users, here’s a one-liner setup: 
git clone https://github.com/YorberR/Python_Arcade.git && cd Python_Arcade && pip install -r requirements.txt && streamlit run streamlit_app.py
This method doesn’t use a virtual environment. Only use if you understand the implications.

​
Project Structure

After installation, your directory structure should look like this: 
Python_Arcade/
├── streamlit_app.py          # Main application entry point
├── requirements.txt          # Python dependencies
├── README.md                 # Project documentation
├── blackjack/
│   └── streamlit_game.py    # Blackjack game logic
├── Hangman/
│   ├── streamlit_game.py    # Hangman game logic
│   └── DATA/
│       └── DATA.txt         # Word list for Hangman
└── Rock_paper_or_scissors/
    └── streamlit_game.py    # RPS game logic

​
Configuration Options

​
Streamlit Configuration

You can customize Streamlit’s behavior by creating a .streamlit/config.toml file: 
[server]
port = 8501
headless = false

[browser]
gatherUsageStats = false

[theme]
primaryColor = "#FF4B4B"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F0F2F6"
textColor = "#262730"
font = "sans serif"
Configuration is optional. The app works perfectly with default settings.

​
Running on a Different Port

If port 8501 is already in use: 
streamlit run streamlit_app.py --server.port 8502

​
Running in Headless Mode

To run without opening a browser automatically: 
streamlit run streamlit_app.py --server.headless true

​
Troubleshooting

​
Common Issues and Solutions

Problem: Streamlit isn’t installed or isn’t in your Python path.Solution:
pip install --upgrade streamlit

# If using virtual environment, make sure it's activated:
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
Problem: Insufficient permissions to install packages globally.Solution (choose one):
# Option 1: Use virtual environment (recommended)
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Option 2: Install for current user only
pip install --user -r requirements.txt

# Option 3: Use sudo (not recommended)
sudo pip install -r requirements.txt
Problem: Another application is using port 8501.Solution:
# Find and kill the process using port 8501
# On Linux/macOS:
lsof -ti:8501 | xargs kill -9

# On Windows:
netstat -ano | findstr :8501
taskkill /PID <PID> /F

# Or run on a different port:
streamlit run streamlit_app.py --server.port 8502
Problem: Your Python version is below 3.9.Solution:
# Check your version
python --version

# Install Python 3.9+ using your system's package manager
# Ubuntu/Debian:
sudo apt install python3.9

# macOS (Homebrew):
brew install [email protected]

# Then create a virtual environment with the correct version:
python3.9 -m venv venv
Problem: Streamlit can’t detect or launch your default browser.Solution:
# Manually open your browser and navigate to:
http://localhost:8501

# Or specify browser:
streamlit run streamlit_app.py --browser.serverAddress localhost
Problem: Session state is lost when switching between games.Solution: This is expected behavior. Each game manages its own session state using unique keys:
# Blackjack uses: deck, player_hand, dealer_hand
# Hangman uses: hangman_word, hangman_guessed, hangman_attempts
# RPS uses: rps_user_score, rps_computer_score
State persists within each game but is independent across games.
Problem: Can’t find Hangman/DATA/DATA.txt.Solution: The code has a fallback, but you can verify the file exists:
ls -la Hangman/DATA/DATA.txt

# If missing, the game will use default words:
# ["PYTHON", "STREAMLIT", "DEVELOPER", "AHORCADO"]
The fallback is implemented in Hangman/streamlit_game.py:11:
def read_words_from_file(filepath):
    try:
        with open(filepath, 'r', encoding='utf-8') as file:
            words = [line.strip().upper() for line in file if line.strip()]
        return words
    except FileNotFoundError:
        return ["PYTHON", "STREAMLIT", "DEVELOPER", "AHORCADO"]

​
Updating the Application

To get the latest version of Python Arcade Suite: 
cd Python_Arcade

# Stash any local changes (if you modified the code)
git stash

# Pull the latest changes
git pull origin main

# Reapply your changes (if any)
git stash pop

# Update dependencies
pip install -r requirements.txt --upgrade

​
Uninstalling

To remove Python Arcade Suite:
1

Deactivate Virtual Environment

If you’re using a virtual environment:
deactivate
2

Remove the Directory

Delete the project folder:
rm -rf Python_Arcade
3

Uninstall Streamlit (Optional)

If you only installed Streamlit for this project:
pip uninstall streamlit

​
Advanced Installation

​
Docker Installation

For containerized deployment: 
# Dockerfile
FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8501

CMD ["streamlit", "run", "streamlit_app.py", "--server.address", "0.0.0.0"]
Build and run: 
docker build -t python-arcade .
docker run -p 8501:8501 python-arcade

​
Development Installation

For contributors who want to modify the code: 
# Clone with SSH for push access
git clone [email protected]:YorberR/Python_Arcade.git
cd Python_Arcade

# Create development environment
python -m venv venv-dev
source venv-dev/bin/activate

# Install in editable mode with dev dependencies
pip install -e .
pip install streamlit pytest black flake8

# Run in development mode with auto-reload
streamlit run streamlit_app.py --server.runOnSave true

​
Next Steps

Quickstart Guide

Learn how to play the games

Architecture

Understand the code structure

Games Overview

Explore the available games

Deployment

Deploy to Streamlit Cloud
Need help? Check out the GitHub Issues or open a new issue if you encounter problems.

Build docs developers (and LLMs) love

Get started for freeTalk to us