[!IMPORTANT]
Project Status
This project is actively maintained and developed by 6sfy.
[!CAUTION] The use of this module under a different name on PyPI (or another source besides this GitHub) is not associated with this library. anisama streams from Anime-Sama, Voiranime, MyFluneo, AnimesUltra, French-Anime, AnimoFlix, Franime. We are not responsible for any misuse.
About
Welcome to anisama, a Python CLI to browse, watch, and download anime from multiple sources (VOSTFR/VF).
- Inspired by ani-cli, the original shell-based anime streaming tool.
- Scrapes 7 sources: Anime-Sama, Voiranime, MyFluneo, AnimesUltra, French-Anime, AnimoFlix, Franime.
- Interactive TUI built with Rich and Questionary.
- Connects to the anisama API for fast search and video resolution.
Project Structure
anisama/
├── src/ # Library package (installed as `anisama`)
│ ├── __init__.py # Version and top-level exports
│ ├── config.py # Constants, headers, domains, paths
│ ├── cache.py # Catalog CRUD, multi-source merge
│ ├── search.py # Fuzzy search (rapidfuzz)
│ ├── http_client.py # Shared httpx.Client singleton (HTTP/2)
│ ├── resolver.py # Video URL resolution per host
│ ├── sources.py # Source registry + unified API
│ ├── exceptions.py # Custom exceptions
│ ├── scraper/ # Per-source scrapers
│ │ ├── base.py # Shared helpers, domain discovery
│ │ ├── anime_sama.py # Anime-Sama scraper
│ │ ├── voiranime.py # Voiranime scraper
│ │ ├── myfluneo.py # MyFluneo scraper (Playwright)
│ │ ├── animesultra.py # AnimesUltra scraper
│ │ ├── frenchanime.py # FrenchAnime scraper
│ │ ├── animoflix.py # AnimoFlix scraper (Playwright)
│ │ └── franime.py # Franime scraper (API-based)
│ └── cli/ # CLI-specific code
│ ├── app.py # Entry point, click command
│ ├── display.py # Banner, colors, info panels
│ ├── workflow.py # Main workflow (search, play, download)
│ ├── picker.py # Selection menus
│ ├── player.py # Player detection, play/download
│ ├── mirror.py # Speed tests, mirror resolution
│ ├── install.py # yt-dlp/ffmpeg install guides
│ ├── settings.py # Settings menu
│ └── api_client.py # Remote anisama API client
├── data/ # Local catalog/settings storage
├── tests/ # Pytest suite
└── pyproject.toml
Features
- Search anime by title with fuzzy matching (rapidfuzz) across 7 sources
- Multi-source merge: Anime-Sama, Voiranime, MyFluneo, AnimesUltra, French-Anime, AnimoFlix, Franime
- Intelligent dedup: season/lang variants grouped under one result
- Smart search: exact match shows only relevant results, broad queries show variants
- Browse seasons (VOSTFR / VF)
- Stream episodes in your preferred video player
- Download episodes directly
- Episode range support (1-5 or 1,3,5)
- Multiple video mirrors with automatic speed-tested fallback
- Player support: mpv, VLC, IINA, MoonPlayer, ImPlay
- API-first resolve with local fallback
- "Continue watching" history menu
- AniList-powered info panel (score, status, episodes, studios, tags, synopsis)
- Prefer MP4 sources over HLS/m3u8 for faster playback
- Automatic m3u8 → mp4 conversion for downloads
Installation
From PyPI (recommended)
pip install anisama
With Playwright support
pip install anisama[playwright]
playwright install chromium
From source
git clone https://github.com/6sfy/anisama.git
cd anisama
pip install -e .
Usage
Interactive mode
anisama
CLI mode
anisama "demon slayer"
anisama "one piece" -e 1-5
anisama "attack on titan" -e 1,3,5 --lang vf
anisama "jujutsu kaisen" -d -e 1
anisama -p vlc "berserk"
Options
| Flag | Description |
|---|---|
--lang vostfr/vf |
Language filter |
--dub |
Shorthand for VF |
-d, --download |
Download instead of streaming |
-e, --episodes |
Episode range: 5, 1-5, or 1,3,5 |
-p, --player |
Player: mpv, vlc, iina, moonplayer, implay |
-U, --update |
Force refresh the anime catalog |
-s, --settings |
Open settings menu |
-q, --quiet |
Reduce output verbosity |
--version |
Show version |
-h, --help |
Show help |
API
anisama uses a centralized API for fast search and video resolution. The API server source is available at github.com/6sfy/anisama-api.
The API base URL defaults to https://anisama.sexcaller.lol and can be overridden with the ANISAMA_API environment variable.
As a library
from anisama import cache, search, resolver
from anisama.scraper import anime_sama, voiranime
from anisama.scraper.base import find_active_domain
from anisama.sources import SOURCES
from anisama.config import KNOWN_DOMAINS, DEFAULT_HEADERS
# Find active domain
domain = find_active_domain()
# Download catalog
catalog = cache.download_combined_catalog(domain)
# Search
results = search.search_combined("demon slayer", catalog, domain)
# Get episodes
seasons = anime_sama.get_anime_seasons(results[0]["link"])
episodes = anime_sama.get_episodes(seasons[0]["url"])
# Resolve video URL
video = resolver.resolve_url(episodes[0]["mirrors"]["eps1"])
# Use the unified source registry
for name, source in SOURCES.items():
print(f"{name}: {source.description}")
Configuration
ANISAMA_API— Override the API base URL (default:https://anisama.sexcaller.lol)ANISAMA_DATA_DIR— Override the data directory (default:<project_root>/data)ANISAMA_PLAYWRIGHT_EXECUTABLE_PATH— Path to Playwright Chromium executable
Sources
| Source | Language | Method |
|---|---|---|
| Anime-Sama | VOSTFR/VF | HTML scraping |
| Voiranime | VOSTFR/VF | HTML scraping |
| MyFluneo | VOSTFR | Playwright |
| AnimesUltra | VOSTFR/VF | Sitemap/HTML |
| French-Anime | VOSTFR/VF | HTML scraping |
| AnimoFlix | VOSTFR | HTML + Playwright |
| Franime | VOSTFR/VF | API |
Contributing
- Before creating an issue, please ensure that it hasn't already been reported/suggested.
- See the contribution guide if you'd like to submit a PR.
Credits
- pystardust/ani-cli for the original idea and workflow
- Content sources: Anime-Sama, Voiranime, MyFluneo, AnimesUltra, French-Anime, AnimoFlix, Franime
Metadata
Release files for anisama 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| anisama-2.1.0.tar.gz | 62.5 kB | With provenance | Details for anisama-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| anisama-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for anisama-2.1.0-py3-none-any.whl |
Total release size: 132.2 kB
Release files / anisama-2.1.0.tar.gz
| Download URL | anisama-2.1.0.tar.gz |
|---|---|
| Size | 62.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e447af4700c35499c08a5c366f87cc3de61e9952a2e96b98c20f086c3915ed86
|
|
BLAKE2b-256 checksum How to use checksums |
4ff0d26fd521a6be22279ddf1561f7cc6ae53da670ed8d8b210d2a6c6bc42ea2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 17, 2026.
Transparency logRelease files / anisama-2.1.0-py3-none-any.whl
| Download URL | anisama-2.1.0-py3-none-any.whl |
|---|---|
| Size | 69.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f203ab3da66ee6b43a27f4e421f849f8947e7b508c46794ab76e3e08a0d935f
|
|
BLAKE2b-256 checksum How to use checksums |
89e1e4e7cf3e9b9737526a2b34bb19910af8e32d1b810119cd23391bbb944300
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 17, 2026.
Transparency logSecurity for anisama 2.1.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for anisama-2.1.0.tar.gz
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 Aug 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.