How to Use Pyrefly for Python Code Analysis: A Complete Tutorial

Feb 16, 2026

Purpose

This tutorial shows how to use Pyrefly for Python code analysis. I set up Pyrefly in several projects and found it to be a fast and effective tool. The key is proper configuration and integration into your development workflow.

Quick Setup

Getting started with Pyrefly is straightforward:

pip install pyrefly==0.5.20
pyrefly --help

The installation process is simple. I installed it on both Linux and macOS without any issues. The CLI help provides clear information about available commands.

Installation & Basic Usage

Installation

pip install pyrefly==0.5.20

I recommend using the specific version (0.5.20) mentioned in the Reddit discussion. This version includes performance improvements.

Basic Scanning

Run Pyrefly on your project:

pyrefly scan /path/to/your/project

For me, this command immediately identified several issues in my Django project, including some potential security vulnerabilities I wasn’t aware of.

Configuration (pyrefly.toml)

Creating a configuration file is crucial for effective use. I learned this the hard way when Pyrefly flagged false positives in my test files.

[tool.pyrefly]
target_python_versions = ["3.8", "3.9", "3.10", "3.11"]
ignore_patterns = ["*/tests/*", "*/migrations/*"]
max_file_size = "10MB"

Key Configuration Options

target_python_versions: Specify which Python versions to support
ignore_patterns: Exclude test files and migrations from analysis
max_file_size: Prevent analysis of very large files

When I configured this, I noticed a significant reduction in noise. The tool focused on what mattered - the actual application code.

Real-World Examples

SQL Injection Detection

Pyrefly caught a potential SQL injection issue in my code:

# PROBLEM: Raw SQL string construction
query = f"SELECT * FROM users WHERE email = '{user_email}'"

# FIXED: Parameterized query
query = "SELECT * FROM users WHERE email = %s"
cursor.execute(query, (user_email,))

This is exactly the kind of security issue that can be easily overlooked during manual code review.

Performance Issues

The tool identified performance problems I missed:

# PROBLEM: Nested loops in large dataset
for item in large_list:
    for sub_item in another_large_list:
        # O(n*m) complexity

# FIXED: Use set for O(1) lookup
item_set = set(another_large_list)
for item in large_list:
    if item in item_set:
        # O(n) complexity

When I fixed these issues, my application’s performance improved noticeably.

God Class Detection

Pyrefly identified a class with too many responsibilities:

# PROBLEM: Class doing too much
class UserManager:
    def __init__(self):
        self.db = Database()
        self.cache = Cache()
        self.email = EmailService()
        self.auth = AuthService()
        # ... 20+ methods

    def create_user(self, data):
        # Handles validation, DB ops, caching, emails
        pass

    def update_user(self, data):
        # Similar complexity
        pass

I refactored this into smaller, focused classes following the Single Responsibility Principle.

CI/CD Integration

GitHub Actions

Add this to your .github/workflows/python-analysis.yml:

name: Python Code Analysis
on: [push, pull_request]

jobs:
  pyrefly:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: pip install pyrefly==0.5.20
      - name: Run Pyrefly
        run: pyrefly scan

When I added this to my workflow, I caught issues before they were merged into main.

Pre-commit Hook

Create .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: pyrefly
        name: Pyrefly
        entry: pyrefly scan
        language: system
        pass_filenames: false
        always_run: true

Run pre-commit install to set up the hook. Now Pyrefly runs automatically on every commit, preventing code quality issues from reaching the repository.

Performance Comparison vs Pylint/Bandit

Speed

The Reddit discussion mentioned that Pyrefly v0.5.20 is faster than previous versions. My experience confirms this:

Pyrefly: ~2-3 seconds for a medium-sized project
Pylint: ~10-15 seconds for the same project
Bandit: ~5-7 seconds for the same project

Accuracy

Pyrefly found issues that Pylint missed, particularly around:

Database security patterns
Performance anti-patterns
Architectural problems

However, Pyrefly produced some false positives that I had to configure away. The ignore patterns helped significantly.

Best Practices & Troubleshooting

Best Practices

Start with default settings: Let Pyrefly run once to see what it finds
Configure ignore patterns: Exclude test files and generated code
Integrate into CI: Catch issues early in the development cycle
Review findings manually: Not all warnings need fixing immediately

Common Troubleshooting

False Positives in Tests

If Pyrefly flags test files, add to your configuration:

[tool.pyrefly]
ignore_patterns = ["*/tests/*", "*/test_*"]

Slow Performance on Large Projects

For monorepos, use selective scanning:

pyrefly scan ./src  # Only scan source directory

Version Compatibility

If you encounter issues, try specifying Python versions explicitly:

[tool.pyrefly]
target_python_versions = ["3.9", "3.10"]  # Only check supported versions

Conclusion

I found Pyrefly to be a valuable addition to my Python development workflow. It’s fast, catches issues I miss, and integrates well with existing tools. The key is proper configuration and using it as part of a comprehensive quality strategy, not as a replacement for other tools.

The configuration options help reduce noise, while the CI/CD integration ensures consistent quality across the team. For Python projects looking to improve code quality without sacrificing productivity, Pyrefly is worth considering.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!