How to Set Up Sourcery AI in PyCharm: Step-by-Step

Why set up Sourcery AI in PyCharm

Getting code quality feedback during development is far more efficient than waiting for PR review. When a reviewer flags a refactoring issue on your pull request, you have already moved on to the next task. Context-switching back to fix readability problems and apply cleaner patterns adds friction that compounds across every PR in your workflow.

Sourcery eliminates this delay by bringing AI-powered code analysis directly into PyCharm. The Sourcery plugin analyzes your Python code as you write it, surfacing refactoring suggestions, readability improvements, and code quality metrics in real time. Instead of discovering that your nested loop should be a list comprehension during PR review, you see the suggestion inline while you are still thinking about the function.

For Python developers who use PyCharm as their primary IDE, the Sourcery plugin is a natural fit. PyCharm already offers strong code analysis and refactoring capabilities through its built-in inspections. Sourcery adds an AI-powered layer on top that catches higher-level improvements - idiomatic patterns, unnecessary complexity, and structural refactoring opportunities that rule-based inspections miss.

The Sourcery PyCharm plugin also works across other JetBrains IDEs built on the IntelliJ platform. If you use IntelliJ IDEA, WebStorm, or any other JetBrains product, the same plugin provides identical functionality. This guide focuses on PyCharm since that is where Sourcery’s Python-specific features deliver the most value, but every step applies equally to other IntelliJ-based editors.

This guide covers every step of setting up Sourcery in PyCharm - from installing the plugin to configuring code quality metrics, keyboard shortcuts, team settings, and troubleshooting common issues. If you are looking for the VS Code version of this guide, see Sourcery VS Code setup. For a full platform overview, read our Sourcery review.

Prerequisites

Before you begin, confirm you have the following:

• PyCharm 2021.3 or later installed on your machine. The Sourcery plugin requires a recent version of PyCharm. Check your version by going to Help and then About in the menu bar. Both PyCharm Community Edition and PyCharm Professional are supported.
• A GitHub or Google account for signing in to Sourcery. The plugin requires authentication to activate, even on the free tier. No separate Sourcery account creation is needed.
• Python 3.7 or later configured as your project interpreter. Sourcery’s deepest analysis targets Python, so having a Python project ready will let you immediately test the plugin after installation.
• An active internet connection during initial setup and authentication. After sign-in, most analysis runs locally, but some features require connectivity to Sourcery’s servers.

No API keys, license files, or separate Sourcery account registration is required. The plugin handles everything through your existing GitHub or Google credentials.

Step 1 - Install the Sourcery plugin from the JetBrains Marketplace

Open PyCharm and navigate to the plugin settings. The quickest way is to press Ctrl+Alt+S on Windows and Linux or Cmd+, on macOS to open the Settings dialog.

1. In the Settings dialog, select Plugins from the left sidebar
2. Click the Marketplace tab at the top of the Plugins panel
3. Type Sourcery in the search bar
4. Find the official plugin published by sourcery.ai - verify the publisher name to avoid installing unofficial copies
5. Click the Install button next to the Sourcery plugin
6. When prompted, click Restart IDE to complete the installation

After PyCharm restarts, the Sourcery plugin is installed but not yet activated. You will see a new Sourcery icon in the right-side toolbar or the bottom tool window bar, depending on your PyCharm version and layout configuration.

If you prefer installing from the command line or using a plugin zip file, you can also download the plugin directly from the JetBrains Marketplace website and install it through Settings, then Plugins, then the gear icon, then Install Plugin from Disk. However, the Marketplace tab method described above is the simplest and ensures automatic updates.

Plugin name: Sourcery
Publisher: sourcery.ai
Compatible with: IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs

Step 2 - Sign in and authenticate

Click the Sourcery icon in the PyCharm toolbar to open the Sourcery panel. You will see a prompt to sign in before the plugin begins analyzing your code.

1. Click Sign in with GitHub or Sign in with Google depending on your preference
2. Your default browser opens and redirects you to the Sourcery authentication page
3. Authorize Sourcery to access your account when prompted by the OAuth screen
4. After successful authorization, the browser displays a confirmation message
5. Switch back to PyCharm - the plugin automatically detects the completed sign-in

The Sourcery panel in PyCharm should now show your account name and a status indicator confirming that the plugin is active. If you see an “Active” status or a green indicator, the plugin is ready to analyze your code.

For teams using the Pro or Team plan, your plan features activate automatically based on your account credentials. There is no separate license key to enter or activation code to redeem.

Troubleshooting sign-in issues: If the browser does not open automatically, check the PyCharm Event Log (View, then Tool Windows, then Event Log) for a link you can copy and paste into your browser manually. If sign-in fails repeatedly, verify that your firewall or VPN is not blocking connections to sourcery.ai. Corporate proxies sometimes interfere with OAuth callbacks - in this case, configure PyCharm’s proxy settings under Settings, then Appearance and Behavior, then System Settings, then HTTP Proxy.

Step 3 - Get your first real-time refactoring suggestions

Open any Python file in your project to see Sourcery in action. The plugin analyzes the file automatically and surfaces suggestions inline within the editor.

Here is an example of code that Sourcery will flag for refactoring:

# Before - Sourcery will suggest a refactoring
def get_discounted_prices(products):
    discounted = []
    for product in products:
        if product.on_sale:
            discounted.append(product.price * 0.9)
    return discounted

Sourcery highlights the function and suggests replacing the loop with a list comprehension:

# After - Sourcery's suggested refactoring
def get_discounted_prices(products):
    return [product.price * 0.9 for product in products if product.on_sale]

Suggestions appear in several ways within PyCharm:

• Inline highlights - subtle underlines or gutter icons on lines where Sourcery has suggestions. The gutter icon appears in the left margin next to the line number.
• Intention actions - press Alt+Enter on Windows and Linux or Option+Enter on macOS when your cursor is on a highlighted line to see available Sourcery quick fixes alongside PyCharm’s own intentions.
• Inspections panel - Sourcery findings appear in PyCharm’s Inspections results when you run Analyze, then Inspect Code. This gives you a project-wide overview of all available refactoring opportunities.
• Hover tooltips - hovering over underlined code shows the suggestion details, including an explanation of why the change improves the code and a preview of the refactored version.

To apply a suggestion, press Alt+Enter (or Option+Enter on macOS) and select the Sourcery refactoring from the intentions menu. The change is applied immediately, and you can undo it with Ctrl+Z if the result does not match your expectations.

Sourcery catches a wide range of Python-specific patterns:

• Nested conditionals that can be flattened using guard clauses or early returns
• Loops that can be replaced with list comprehensions, dictionary comprehensions, or generator expressions
• Verbose boolean expressions that can be simplified
• Missing use of context managers for file handling and resource management
• Opportunities to use enumerate() instead of manual index tracking
• String concatenation that should use f-strings or str.join()
• Redundant variable assignments that can be inlined
• Opportunities to use dataclasses instead of manual __init__ methods

Step 4 - Understand code quality metrics

Sourcery provides code quality metrics that give you a quantitative view of your code’s readability and complexity. These metrics appear in the Sourcery panel and help you identify which parts of your codebase need the most attention.

Sourcery measures four dimensions of code quality:

Complexity tracks the cyclomatic complexity of your functions and methods. High complexity scores indicate functions with many branches, nested conditionals, and decision points. Sourcery flags functions that exceed reasonable complexity thresholds and suggests ways to simplify them - typically through early returns, guard clauses, or extracting helper functions.

Method length monitors the line count of your functions. Long methods are harder to read, test, and maintain. Sourcery highlights functions that exceed recommended length thresholds and suggests extraction points where you can split a long method into smaller, focused functions.

Working memory measures how many variables and concepts a developer needs to hold in their head while reading a function. Functions with high working memory scores require the reader to track many variables, nested scopes, and state changes simultaneously. Sourcery suggests refactoring patterns that reduce working memory - such as extracting complex expressions into named variables or splitting a function into sequential steps.

Overall quality score combines the individual metrics into a single percentage score for each function. This makes it easy to identify the lowest-quality functions in your codebase and prioritize refactoring efforts. Functions scoring below 25% are typically strong candidates for restructuring.

These metrics are not arbitrary - they correlate with real maintenance costs. Functions with high complexity and working memory scores are statistically more likely to contain bugs and take longer to modify safely. Using Sourcery’s quality metrics as a guide helps you focus refactoring effort where it delivers the most impact.

Step 5 - Configure Sourcery for your project

Sourcery’s behavior can be customized through a project-level configuration file and PyCharm’s settings panel. The combination gives you fine-grained control over what Sourcery analyzes and what it ignores.

PyCharm settings

Open PyCharm Settings (Ctrl+Alt+S or Cmd+,) and search for “Sourcery” to see available options:

Setting	Description	Default
Sourcery code lens	Show refactoring suggestions as inline hints above functions	Enabled
Sourcery diagnostics	Show Sourcery findings in PyCharm’s inspection results	Enabled
Sourcery metrics	Display code quality metrics in the Sourcery panel	Enabled

Project configuration with .sourcery.yaml

For project-specific settings that apply consistently across all team members and IDEs, create a .sourcery.yaml file in your project root:

# .sourcery.yaml
refactor:
  skip:
    - low-code-quality
    - no-suitable-type
  rule_types:
    - refactoring
    - suggestion
    - comment

clone_detection:
  min_lines: 3
  min_duplicates: 2

github:
  labels: []
  ignore_labels:
    - sourcery-ignore

ignore:
  - data/generated_*.py
  - "*/migrations/*"
  - tests/fixtures/**
  - "*.pyi"
  - venv/**
  - .venv/**

The .sourcery.yaml file is the single source of truth for Sourcery configuration across all environments. The same file controls behavior in PyCharm, VS Code, and the GitHub integration. This means your team gets consistent analysis regardless of which editor each developer uses.

The refactor.skip list lets you disable specific suggestion categories. If your team finds certain suggestion types unhelpful - for example, suggestions to convert simple if/else blocks that are already readable - add the rule ID to this list.

The ignore section excludes files and directories from analysis. This is essential for generated code, database migrations, test fixtures, virtual environments, and stub files that follow different patterns or should not be modified by Sourcery.

The clone_detection section configures Sourcery’s duplicate code detection. Set min_lines to control how many consecutive similar lines trigger a duplication warning, and min_duplicates to control how many copies must exist before Sourcery flags the pattern.

Step 6 - Set up keyboard shortcuts

Efficient use of Sourcery in PyCharm requires integrating its actions into your keyboard shortcut workflow. PyCharm’s keymap system lets you assign custom shortcuts to any Sourcery action.

Default keyboard interactions

Sourcery leverages PyCharm’s existing intention action system. The most important shortcut is:

• Alt+Enter (Windows/Linux) or Option+Enter (macOS) - when your cursor is on a line with a Sourcery suggestion, this opens the intentions menu showing available refactoring options. This is the same shortcut PyCharm uses for its own quick fixes, so Sourcery’s suggestions appear alongside PyCharm’s native intentions.

Assigning custom shortcuts

To assign shortcuts to specific Sourcery actions:

1. Open Settings (Ctrl+Alt+S or Cmd+,)
2. Navigate to Keymap
3. Search for Sourcery in the search bar
4. Right-click on any Sourcery action and select Add Keyboard Shortcut
5. Press the key combination you want to assign and click OK

Common actions worth binding to shortcuts include:

• Sourcery: Review current file - triggers a full analysis of the active file
• Sourcery: Open chat - opens the Sourcery AI chat panel for contextual questions
• Sourcery: Toggle suggestions - hides or shows Sourcery’s inline suggestions temporarily

Recommended shortcut assignments

For developers who use Sourcery frequently, consider these bindings that avoid conflicts with PyCharm’s default keymap:

Action	Suggested Shortcut (Windows/Linux)	Suggested Shortcut (macOS)
Review current file	Ctrl+Shift+Alt+R	Cmd+Shift+Option+R
Open Sourcery chat	Ctrl+Shift+Alt+C	Cmd+Shift+Option+C
Toggle suggestions	Ctrl+Shift+Alt+S	Cmd+Shift+Option+S

These shortcuts use the Ctrl+Shift+Alt modifier combination on Windows and Linux (or Cmd+Shift+Option on macOS), which is rarely used by PyCharm’s default keymap and minimizes the chance of conflicts with other plugins.

Step 7 - Suppress unwanted suggestions

Not every Sourcery suggestion will be relevant to your codebase. Learning how to suppress individual suggestions and entire categories ensures that Sourcery’s output stays useful rather than becoming noise.

Inline suppression with comments

Add a # sourcery skip comment directly above the line or block you want to exclude:

# sourcery skip: list-comprehension
def process_items(items):
    results = []
    for item in items:
        if item.is_valid():
            results.append(transform(item))
    return results

The comment tells Sourcery to skip the specific suggestion type for the following code block. You can specify the rule ID after the colon (like list-comprehension above) to suppress only that specific suggestion while allowing other suggestions to appear on the same code.

To suppress all Sourcery suggestions for an entire function or class:

# sourcery skip
def legacy_function():
    # This function intentionally uses patterns that Sourcery would flag
    # because it mirrors an external API's behavior exactly
    pass

Global suppression in .sourcery.yaml

For patterns that your entire team agrees should be ignored, add them to the refactor.skip list in your .sourcery.yaml file:

refactor:
  skip:
    - low-code-quality
    - use-contextlib-suppress
    - merge-nested-ifs
    - use-named-expression

This suppresses the listed suggestion types across the entire project, for all team members, in every environment - PyCharm, VS Code, and GitHub PR reviews.

Dismissing through the PyCharm interface

When Sourcery shows a suggestion in the intentions menu (Alt+Enter), you can dismiss it rather than applying it. Sourcery tracks dismissals and uses them to adjust the relevance of similar suggestions in the future. Teams that actively dismiss unhelpful suggestions during the first two to three weeks of adoption see a meaningful reduction in noise as Sourcery adapts to their preferences.

Step 8 - Configure team settings

For teams using Sourcery’s Team plan, additional configuration options enable consistent code quality standards across all team members. These settings ensure that every developer on the team gets the same analysis, regardless of their individual PyCharm setup.

Shared .sourcery.yaml configuration

The most important team setting is a shared .sourcery.yaml file committed to your repository root. Since this file controls Sourcery’s behavior across all IDEs and the GitHub integration, it serves as your team’s single source of truth for code quality rules. Every developer who clones the repository automatically gets the same Sourcery configuration.

# Team .sourcery.yaml example
refactor:
  skip:
    - low-code-quality
  rule_types:
    - refactoring
    - suggestion
    - comment

rules:
  - id: no-print-statements
    description: Use logging instead of print statements
    pattern: print(...)
    replacement: logger.info(...)
    language: python
    severity: warning

  - id: require-docstrings
    description: Public functions should have docstrings
    pattern: |
      def ${name}(${args}):
          ...
    condition: name[0] != '_'
    language: python
    severity: info

ignore:
  - "*/migrations/*"
  - tests/fixtures/**
  - venv/**
  - .venv/**

Custom coding guidelines

On the Team plan, Sourcery supports custom coding guidelines that go beyond simple pattern matching. You can define natural language guidelines that describe your team’s conventions, and Sourcery’s AI engine interprets these during analysis:

coding_guidelines:
  - title: Error handling
    description: All database operations must be wrapped in try/except blocks with specific exception types. Never use bare except clauses. Log all exceptions with full stack traces.
  - title: API response format
    description: All API endpoints must return responses using our standard envelope format with data, error, and meta fields. Never return raw data objects.

These guidelines apply across PyCharm, VS Code, and GitHub - giving every developer the same feedback regardless of their tooling choice.

Repository analytics

The Team plan includes repository analytics dashboards that show aggregate code quality metrics across your team. While these dashboards are accessed through the Sourcery web interface rather than PyCharm directly, the data is driven by the same analysis that runs in the IDE. Analytics help team leads identify which parts of the codebase have the lowest quality scores and where refactoring effort should be prioritized.

Step 9 - Use the Sourcery chat assistant

Sourcery includes an AI chat assistant that provides contextual help directly inside PyCharm. The chat assistant understands the file you are editing and can answer questions about your code, suggest refactoring approaches, and help with debugging.

To open the chat assistant, click the Sourcery icon in the PyCharm tool window bar (typically on the right side or bottom of the IDE). The chat panel opens as a tool window that you can dock, float, or resize like any other PyCharm panel.

Common uses for the chat assistant:

• Explain a function - ask “What does this function do?” and Sourcery provides a plain-language explanation based on the code context
• Suggest refactoring - ask “How can I simplify this function?” and Sourcery offers specific, actionable refactoring steps
• Debug assistance - paste an error message and ask “Why am I getting this error?” and Sourcery analyzes the relevant code to identify potential causes
• Generate tests - ask “Write unit tests for this function” and Sourcery generates test cases covering common scenarios and edge cases
• Code review - ask “Review this function for potential issues” and Sourcery provides a mini code review with actionable feedback

The chat assistant is available on both free and paid plans. On paid plans, the assistant has access to more context about your project structure and can provide more detailed responses.

Troubleshooting common issues

If Sourcery is not working as expected in PyCharm, work through these solutions in order.

Plugin not appearing after installation. Verify that PyCharm was fully restarted after installation - a simple window reload is not sufficient. Go to Settings, then Plugins, then Installed, and confirm that Sourcery appears in the list and its checkbox is enabled. If the plugin is listed but disabled, enable it and restart again.

Authentication failing or token expired. Open the Sourcery panel in PyCharm and click Sign Out, then sign in again with your GitHub or Google account. If the browser redirect fails, check the PyCharm Event Log for a manual authentication link. Corporate VPNs and proxy servers are the most common cause of authentication failures - configure PyCharm’s HTTP proxy settings if you are behind a corporate firewall.

No suggestions appearing on Python files. Verify that your Python interpreter is configured correctly in PyCharm (File, then Settings, then Project, then Python Interpreter). Sourcery needs to detect a valid Python project before it begins analysis. Also check that the file is not excluded by an ignore pattern in your .sourcery.yaml file. If you are working on a private repository, a Pro or Team plan is required for analysis.

Suggestions appearing too slowly. Sourcery runs analysis asynchronously, but large files (over 500 lines) may take several seconds to process. If performance is consistently slow, check PyCharm’s memory allocation (Help, then Change Memory Settings) and consider increasing the heap size. Also exclude large generated files and data files from analysis using the .sourcery.yaml ignore configuration.

Conflicts with other plugins. Sourcery generally coexists well with other PyCharm plugins, including other AI-powered tools. If you experience issues, try disabling other AI plugins temporarily to isolate the conflict. Plugins that register their own intention actions or inspections are the most likely to create conflicts. Check the PyCharm Event Log for error messages that identify the specific conflict.

Plugin not recognizing .sourcery.yaml changes. Sourcery reads the .sourcery.yaml file when the project is opened. If you modify the file while PyCharm is running, the changes should take effect automatically. If they do not, close and reopen the project (File, then Close Project, then reopen). Verify that the file is named exactly .sourcery.yaml (not .sourcery.yml or sourcery.yaml) and that it is located in the project root directory.

Sourcery showing outdated suggestions after code changes. The plugin re-analyzes files after edits, but there is a brief debounce delay to avoid analyzing incomplete changes. If suggestions seem stale, save the file (Ctrl+S or Cmd+S) and wait two to three seconds for the analysis to refresh. If the problem persists, close and reopen the file.

For details on Sourcery’s pricing tiers and what each plan includes, see our Sourcery pricing guide.

Sourcery in PyCharm vs Sourcery in VS Code

Both IDE integrations offer the same core analysis engine, but the developer experience differs based on each editor’s architecture.

PyCharm’s integration leverages the IntelliJ platform’s inspection system, which means Sourcery suggestions appear alongside PyCharm’s own built-in inspections. This creates a unified experience where you browse all code quality findings - both PyCharm’s native inspections and Sourcery’s AI-powered suggestions - in one place through the Inspections panel. PyCharm’s stronger refactoring infrastructure also means that applying Sourcery’s suggestions integrates smoothly with PyCharm’s undo history and local history features.

The VS Code integration uses the Language Server Protocol (LSP) and presents suggestions through VS Code’s code actions and diagnostics systems. If you work across both editors or want to compare the two setups, see our Sourcery VS Code setup guide.

The .sourcery.yaml configuration file works identically in both editors, and the chat assistant provides the same functionality regardless of IDE. Teams with mixed editor preferences can standardize on a shared .sourcery.yaml and get consistent analysis across all environments.

Alternatives to Sourcery for PyCharm

If Sourcery does not meet your needs, several alternatives provide code quality analysis within PyCharm or the broader JetBrains ecosystem.

CodeAnt AI ($24-40/user/month) is a comprehensive code quality platform that bundles AI-powered code review, static analysis (SAST), secret detection, and DORA metrics into a single tool. While it focuses primarily on PR-level review through GitHub, GitLab, and Bitbucket rather than real-time IDE analysis, it provides broader coverage for teams that need security scanning and compliance reporting alongside code quality feedback. For teams that need more than just refactoring suggestions, CodeAnt AI’s breadth makes it worth evaluating.

GitHub Copilot ($19-39/user/month) provides AI code completion, generation, and chat directly in PyCharm through its JetBrains plugin. Copilot is stronger for code generation and completion workflows, while Sourcery is more focused on code quality and refactoring. Teams that want both capabilities can run them side by side.

Pylint (free) is the most comprehensive Python linter with hundreds of configurable rules. It integrates with PyCharm’s external tools system and catches a wide range of style violations, errors, and code smells. Pylint is deterministic rather than AI-powered, making it a complement to Sourcery rather than a replacement. For a detailed comparison, see our Sourcery vs Pylint guide.

Ruff (free) is the fastest Python linter available, written in Rust with over 800 rules. It replaces Flake8, isort, Black, and pycodestyle in a single tool. Ruff has a PyCharm plugin that provides instant feedback on style violations and common bugs. Like Pylint, Ruff complements Sourcery by handling deterministic linting while Sourcery handles AI-powered refactoring.

For a comprehensive comparison of all options, see our Sourcery alternatives guide.

Connecting PyCharm to Sourcery’s GitHub integration

Using Sourcery in PyCharm and on GitHub together gives you feedback at two stages of the development workflow. The PyCharm plugin catches issues while you write code. The GitHub integration catches issues during PR review. Together, they significantly reduce the chance that code quality problems reach production.

Setting up the GitHub integration is a separate process from the PyCharm plugin. The GitHub integration installs as a GitHub App on your repositories and reviews pull requests automatically. See our Sourcery GitHub integration guide for the full setup walkthrough.

When both are active, the workflow looks like this:

1. Write code in PyCharm with Sourcery providing real-time suggestions
2. Apply relevant suggestions before committing
3. Push your branch and open a pull request
4. Sourcery on GitHub reviews the PR diff and catches any remaining issues that slipped through IDE-level review
5. Address the PR feedback and merge with confidence

This two-stage approach mirrors how experienced teams use linters - running them locally during development and again in CI to catch anything that was missed. Sourcery applies the same principle to AI-powered code quality analysis.

Conclusion

Setting up Sourcery AI in PyCharm takes under 10 minutes and immediately begins providing value through inline refactoring suggestions, code quality metrics, and an AI chat assistant. The combination of PyCharm’s robust IDE infrastructure with Sourcery’s Python-specific intelligence creates a practical setup for any Python developer.

The key steps are straightforward: install the plugin from the JetBrains Marketplace, sign in with GitHub or Google, and start coding. From there, create a .sourcery.yaml file to customize analysis for your project, assign keyboard shortcuts for efficient workflow integration, suppress unhelpful suggestions so Sourcery learns your preferences, and configure team settings for consistent standards across your organization.

For the strongest setup, combine Sourcery’s PyCharm plugin with its GitHub integration for PR-level review, and pair it with a deterministic linter like Ruff or Pylint for comprehensive Python code quality coverage. If you need broader platform support, integrated security scanning, or coverage beyond Python, CodeAnt AI ($24-40/user/month) is worth evaluating as an alternative that bundles multiple code quality capabilities into a single platform.

For more on Sourcery’s capabilities and pricing, explore our Sourcery review and Sourcery pricing guide.