0
# fake-useragent
1

2
Up-to-date simple useragent faker with real world database. This library provides a comprehensive user-agent faker that generates realistic browser user-agent strings from a real-world database, supporting filtering by browser type, operating system, platform, and version.
3

4
## Package Information
5

6
- **Package Name**: fake-useragent
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install fake-useragent`
10

11
## Core Imports
12

13
```python
14
from fake_useragent import UserAgent
15
```
16

17
Alternative imports:
18

19
```python
20
from fake_useragent import FakeUserAgent  # Primary class (alias for UserAgent)
21
from fake_useragent import UserAgent, FakeUserAgentError, UserAgentError  # With exceptions
22
from fake_useragent import __version__  # Version info
23
from fake_useragent import get_version  # Version module
24
from fake_useragent.get_version import __version__  # Alternative version import
25
```
26

27
## Basic Usage
28

29
```python
30
from fake_useragent import UserAgent
31

32
# Create a UserAgent instance with default settings
33
ua = UserAgent()
34

35
# Get a random user agent string
36
print(ua.random)
37
# Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:132.0) Gecko/20100101 Firefox/132.0
38

39
# Get user agents from specific browsers
40
print(ua.chrome)    # Chrome/Chrome Mobile user agent
41
print(ua.firefox)   # Firefox/Firefox Mobile user agent
42
print(ua.safari)    # Safari/Mobile Safari user agent
43
print(ua.edge)      # Edge/Edge Mobile user agent
44
print(ua.opera)     # Opera/Opera Mobile user agent
45

46
# Dictionary-style access
47
print(ua['Chrome'])  # Same as ua.chrome
48

49
# Get user agent with metadata (returns dictionary)
50
user_agent_data = ua.getRandom
51
print(user_agent_data['useragent'])  # User agent string
52
print(user_agent_data['browser'])    # Browser name
53
print(user_agent_data['os'])         # Operating system
54
```
55

56
## Capabilities
57

58
### UserAgent Class
59

60
Primary class for generating fake user agent strings with extensive filtering and customization options.
61

62
```python { .api }
63
class UserAgent:
64
    """
65
    Fake User Agent retriever.
66
    
67
    Parameters:
68
    - browsers (Optional[Iterable[str]]): Filter by browser names. Default includes Chrome, Firefox, Safari, Edge, Opera, and mobile variants
69
    - os (Optional[Iterable[str]]): Filter by operating systems. Default includes Windows, Linux, Mac OS X, Android, iOS
70
    - min_version (float): Minimum browser version filter. Default: 0.0
71
    - min_percentage (float): Minimum usage percentage filter. Default: 0.0
72
    - platforms (Optional[Iterable[str]]): Filter by platform types (desktop, mobile, tablet). Default: all platforms
73
    - fallback (str): Fallback user agent string if retrieval fails
74
    - safe_attrs (Optional[Iterable[str]]): Attributes protected from browser lookup
75
    """
76
    def __init__(
77
        browsers: Optional[Iterable[str]] = None,
78
        os: Optional[Iterable[str]] = None,
79
        min_version: float = 0.0,
80
        min_percentage: float = 0.0,
81
        platforms: Optional[Iterable[str]] = None,
82
        fallback: str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 Edg/122.0.0.0",
83
        safe_attrs: Optional[Iterable[str]] = None
84
    ): ...
85
```
86

87
### Browser-Specific Properties
88

89
Properties that return user agent strings for specific browsers.
90

91
```python { .api }
92
@property
93
def random() -> str:
94
    """Get a random user agent string from any allowed browser."""
95

96
@property  
97
def chrome() -> str:
98
    """Get a random Chrome user agent string (includes Chrome Mobile and Chrome Mobile iOS)."""
99

100
@property
101
def googlechrome() -> str:
102
    """Alias for chrome property."""
103

104
@property
105
def firefox() -> str:
106
    """Get a random Firefox user agent string (includes Firefox Mobile and Firefox iOS)."""
107

108
@property
109
def ff() -> str:
110
    """Alias for firefox property."""
111

112
@property
113
def safari() -> str:
114
    """Get a random Safari user agent string (includes Mobile Safari)."""
115

116
@property
117
def opera() -> str:
118
    """Get a random Opera user agent string (includes Opera Mobile)."""
119

120
@property
121
def google() -> str:
122
    """Get a random Google app user agent string."""
123

124
@property
125
def edge() -> str:
126
    """Get a random Edge user agent string (includes Edge Mobile)."""
127

128
@property
129
def googlechrome() -> str:
130
    """Alias for chrome property."""
131

132
@property
133
def ff() -> str:
134
    """Alias for firefox property."""
135
```
136

137
### Metadata Properties
138

139
Properties that return user agent data with additional metadata as BrowserUserAgentData dictionaries.
140

141
```python { .api }
142
@property
143
def getRandom() -> BrowserUserAgentData:
144
    """Get a random user agent with metadata."""
145

146
@property
147
def getChrome() -> BrowserUserAgentData:
148
    """Get a Chrome user agent with metadata."""
149

150
@property
151
def getFirefox() -> BrowserUserAgentData:
152
    """Get a Firefox user agent with metadata (Firefox only, not mobile variants)."""
153

154
@property
155
def getSafari() -> BrowserUserAgentData:
156
    """Get a Safari user agent with metadata."""
157

158
@property
159
def getOpera() -> BrowserUserAgentData:
160
    """Get an Opera user agent with metadata."""
161

162
@property
163
def getGoogle() -> BrowserUserAgentData:
164
    """Get a Google user agent with metadata."""
165

166
@property
167
def getEdge() -> BrowserUserAgentData:
168
    """Get an Edge user agent with metadata."""
169
```
170

171
### Core Methods
172

173
Primary methods for retrieving user agents with filtering.
174

175
```python { .api }
176
def getBrowser(browsers: Union[str, list[str]]) -> BrowserUserAgentData:
177
    """
178
    Get a browser user agent based on filters.
179
    
180
    Parameters:
181
    - browsers: Browser name(s) to get, or "random" for any browser
182
    
183
    Returns:
184
    BrowserUserAgentData: User agent with additional metadata
185
    """
186

187
def __getattr__(attr: Union[str, list[str]]) -> Union[str, Any]:
188
    """
189
    Get a user agent string by attribute lookup.
190
    
191
    Parameters:
192
    - attr: Browser name to get, or "random" for any browser
193
    
194
    Returns:
195
    str: User agent string if not a safe_attr, otherwise attribute value
196
    """
197

198
def __getitem__(attr: str) -> Union[str, Any]:
199
    """
200
    Get a user agent by key lookup (dictionary-style access).
201
    
202
    Parameters:
203
    - attr: Browser name to get
204
    
205
    Returns:
206
    str: User agent string if not a safe_attr, otherwise attribute value
207
    """
208
```
209

210
### Type Definitions
211

212
```python { .api }
213
class BrowserUserAgentData(TypedDict):
214
    """Schema for browser user agent data returned by getBrowser and get* properties."""
215
    useragent: str              # The user agent string
216
    percent: float              # Usage percentage of this user agent
217
    type: str                   # Device type: "desktop", "mobile", or "tablet"
218
    device_brand: Union[str, None]  # Device brand name (e.g., "Apple", "Samsung")
219
    browser: Union[str, None]       # Browser name (e.g., "Chrome", "Firefox")
220
    browser_version: str            # Full browser version (e.g., "122.0.0.0")
221
    browser_version_major_minor: float  # Major.minor version (e.g., 122.0)
222
    os: Union[str, None]           # Operating system name (e.g., "Windows", "Android")
223
    os_version: Union[str, None]   # OS version (e.g., "10", "14")
224
    platform: str                  # Platform identifier (e.g., "Win32", "iPhone")
225
```
226

227
### Aliases
228

229
```python { .api }
230
# FakeUserAgent is an alias for UserAgent class
231
FakeUserAgent = UserAgent
232
```
233

234
### Exception Classes
235

236
```python { .api }
237
class FakeUserAgentError(Exception):
238
    """Exception for any problems that are library specific."""
239

240
# Common alias
241
UserAgentError = FakeUserAgentError
242
```
243

244
### Version Information
245

246
```python { .api }
247
__version__: str  # Current package version string
248
```
249

250
### Version Module
251

252
```python { .api }
253
# The get_version module provides version information
254
import fake_useragent.get_version as get_version
255
# Access version via: get_version.__version__
256
```
257

258

259

260
## Advanced Usage Examples
261

262
### Custom Browser Filtering
263

264
```python
265
from fake_useragent import UserAgent
266

267
# Only Chrome and Firefox browsers
268
ua = UserAgent(browsers=['Chrome', 'Firefox'])
269
print(ua.random)  # Will only return Chrome or Firefox user agents
270

271
# Only mobile browsers
272
ua = UserAgent(platforms='mobile')
273
print(ua.random)  # Mobile user agents only
274

275
# Only Linux operating systems
276
ua = UserAgent(os='Linux')
277
print(ua.random)  # Linux user agents only
278

279
# Recent browser versions only (version 120.0 and above)
280
ua = UserAgent(min_version=120.0)
281
print(ua.random)  # Modern browser versions only
282

283
# Combine multiple filters
284
ua = UserAgent(
285
    browsers=['Chrome', 'Firefox'],
286
    os=['Windows', 'Mac OS X'],
287
    platforms='desktop',
288
    min_version=100.0
289
)
290
print(ua.random)  # Desktop Chrome/Firefox on Windows/Mac, version 100+
291
```
292

293
### Getting Detailed Browser Information
294

295
```python
296
from fake_useragent import UserAgent
297

298
ua = UserAgent()
299

300
# Get full browser data
301
browser_data = ua.getRandom
302
print(f"Browser: {browser_data['browser']}")
303
print(f"Version: {browser_data['browser_version']}")
304
print(f"OS: {browser_data['os']} {browser_data['os_version']}")
305
print(f"Platform: {browser_data['platform']}")
306
print(f"Device Type: {browser_data['type']}")
307
print(f"Usage %: {browser_data['percent']}")
308

309
# Get specific browser data
310
chrome_data = ua.getChrome
311
print(f"Chrome UA: {chrome_data['useragent']}")
312
```
313

314
### Error Handling and Fallback
315

316
```python
317
from fake_useragent import UserAgent, FakeUserAgentError
318

319
try:
320
    # Custom fallback user agent
321
    ua = UserAgent(fallback='Custom Browser/1.0')
322
    
323
    # This will use fallback if no matching browsers found
324
    print(ua.unknown_browser)  # Falls back to custom string
325
    
326
except FakeUserAgentError as e:
327
    print(f"Library error: {e}")
328
```
329

330
### Safe Attributes
331

332
```python
333
from fake_useragent import UserAgent
334

335
# Protect specific attributes from being treated as browsers
336
ua = UserAgent(safe_attrs=['shape', 'custom_attr'])
337

338
# These will not be treated as browser lookups
339
ua.shape  # Returns actual attribute value, not user agent
340
ua.custom_attr  # Returns actual attribute value, not user agent
341
```
342

343
## Supported Browsers
344

345
The library supports the following browser names for filtering and lookup:
346

347
- **Desktop Browsers**: Google, Chrome, Firefox, Edge, Opera, Safari
348
- **Mobile Browsers**: Android, Chrome Mobile, Chrome Mobile iOS, Firefox Mobile, Firefox iOS, Mobile Safari, Opera Mobile, Edge Mobile
349
- **Specialized Browsers**: Yandex Browser, Samsung Internet, Mobile Safari UI/WKWebView, DuckDuckGo Mobile, MiuiBrowser, Whale, Twitter, Facebook, Amazon Silk
350

351
## Supported Operating Systems
352

353
- Windows, Linux, Ubuntu, Chrome OS, Mac OS X, Android, iOS
354

355
## Platform Types
356

357
- desktop, mobile, tablet