Football player stats, transfers, and market values — straight from your terminal.
Footstats is an open-source CLI tool that lets you search for any football player and retrieve their profile, transfer history, and match statistics — all from your terminal, powered by data from Transfermarkt.
- Player Search — Search any player by name
- Player Profile — Market value, age, club, position, nationality, and more
- Transfer History — Full transfer history with fees and market values
- Match Stats — Per-game stats including goals, assists, cards, minutes, passes, and shots
- Interactive Menu — Navigate with a single keypress
- Direct Commands — Call any command directly with arguments
| Source | Data |
|---|---|
| Transfermarkt | Market value, transfers, match stats, player profile |
With pip
pip install footstats-cliWith uv (recommended)
uv tool install footstats-cliThat's it — the footstats command is now available globally in your terminal.
# pip
pip install footstats-cli --upgrade
# uv
uv tool upgrade footstats-cli# pip
pip uninstall footstats-cli
# uv
uv tool uninstall footstats-cliFootstats is published on the Python Package Index (PyPI) and can be installed with any Python package manager.
Package Page:: pypi.org/project/footstats-cli
| Detail | Info |
|---|---|
| Latest version | |
| Python requires | 3.13+ |
| License | MIT |
| Monthly downloads |  |
Interactive menu
footstatsDirect commands
footstats player "Cristiano Ronaldo"
footstats transfer-history "Lionel Messi"
footstats stats "Erling Haaland"Options
footstats --help
footstats --versionBy default the tool works out of the box. To customize request behavior, create a .env file in your working directory:
USER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64)...
ACCEPT_LANGUAGE=en-US,en;q=0.5
ACCEPT_ENCODING=gzip, deflate
REQUEST_DELAY=3.0 # seconds between requests — increase if getting blockedfootstats-scraper/
├── src/
│ ├── cli/
│ │ ├── main.py # CLI entry point
│ │ └── utils/ # Display helpers
│ ├── models/ # Dataclasses
│ ├── providers/ # Scraping logic
│ └── utils/ # Config, parsing, requests
├── tests/
├── .env.example
├── pyproject.toml
└── README.md
1. Clone the repository
git clone https://github.com/Marin2409/footstats-cli.git
cd footstats-cli2. Install UV
# macOS
brew install uv
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"3. Install dependencies
uv sync4. Set up environment variables
cp .env.example .env5. Run directly without installing
# With Python
python -m src.cli.main [command] [argument]
# With UV (Recommended)
uv run python -m src.cli.main [command] [argument]| Segment | Description |
|---|---|
src |
Root source folder |
cli |
CLI parent folder |
main |
Entry point file |
command |
Action (e.g. player, stats) |
argument |
Player name (e.g. "Cristiano") |
Run Tests
pytest tests/test_providers.pyThis project is an independent open-source tool and is not affiliated with, endorsed by, or sponsored by Transfermarkt or any other data provider. Use it at your own risk and ensure compliance with their Terms of Service and avoid excessive requests. The REQUEST_DELAY setting in .env helps ensure responsible usage.
Users are solely responsible for ensuring that their use of this software complies with applicable laws, regulations, website terms of service, robots.txt policies, and rate-limiting requirements.
The authors provide this software for educational and research purposes only and make no representations regarding the legality or appropriateness of its use in any particular jurisdiction or against any particular website.
By using this software, you acknowledge that you are responsible for determining whether your use complies with applicable laws, regulations, and the terms of service of any websites you access.
The authors are not responsible for how users choose to use this software.
Contributions are welcome! Please open an issue before submitting a pull request so we can discuss the change.
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Commit your changes (
git commit -m 'Add my feature') - Push to the branch (
git push origin feature/my-feature) - Open a Pull Request
MIT License — see LICENSE for details.