{"id":13445149,"url":"https://github.com/rstudio/reticulate","last_synced_at":"2025-05-12T13:26:33.279Z","repository":{"id":38806024,"uuid":"81120794","full_name":"rstudio/reticulate","owner":"rstudio","description":"R Interface to Python","archived":false,"fork":false,"pushed_at":"2025-05-09T20:41:41.000Z","size":20685,"stargazers_count":1695,"open_issues_count":448,"forks_count":341,"subscribers_count":61,"default_branch":"main","last_synced_at":"2025-05-10T11:52:29.486Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://rstudio.github.io/reticulate","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rstudio.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-02-06T18:59:46.000Z","updated_at":"2025-05-09T20:38:52.000Z","dependencies_parsed_at":"2023-10-12T23:36:40.097Z","dependency_job_id":"833471e0-986e-497c-a243-62a99cd19cb7","html_url":"https://github.com/rstudio/reticulate","commit_stats":{"total_commits":2861,"total_committers":89,"mean_commits":"32.146067415730336","dds":0.7843411394617267,"last_synced_commit":"9133fa3bd40f021336a1a97f07941a89131c4f68"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Freticulate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Freticulate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Freticulate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Freticulate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rstudio","download_url":"https://codeload.github.com/rstudio/reticulate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253411503,"owners_count":21904143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T05:00:24.222Z","updated_at":"2025-05-12T13:26:33.254Z","avatar_url":"https://github.com/rstudio.png","language":"R","funding_links":[],"categories":["2017","R","Table of Contents"],"sub_categories":["Book/monograph Lists and Reviews","Data manipulation"],"readme":"# R Interface to Python\n\n\u003c!-- badges: start --\u003e\n\n[![R-CMD-check](https://github.com/rstudio/reticulate/workflows/R-CMD-check/badge.svg)](https://github.com/rstudio/reticulate/actions)\n\n\u003c!-- badges: end --\u003e\n\nThe **reticulate** package provides a comprehensive set of tools for\ninteroperability between Python and R. The package includes facilities\nfor:\n\n\u003cimg src=\"man/figures/reticulated_python.png\" alt=\"reticulated python\" width=\"200\" align=\"right\" style=\"margin-left: 15px;\"/\u003e\n\n-   Calling Python from R in a variety of ways including R Markdown,\n    sourcing Python scripts, importing Python modules, and using Python\n    interactively within an R session.\n\n-   Translation between R and Python objects (for example, between R and\n    Pandas data frames, or between R matrices and NumPy arrays).\n\n-   Flexible binding to different versions of Python including virtual\n    environments and Conda environments.\n\nReticulate embeds a Python session within your R session, enabling\nseamless, high-performance interoperability. If you are an R developer\nthat uses Python for some of your work or a member of data science team\nthat uses both languages, reticulate can dramatically streamline your\nworkflow!\n\n### Getting started\n\n#### Installation\n\nInstall the **reticulate** package from CRAN as follows:\n\n``` r\ninstall.packages(\"reticulate\")\n```\n\n#### Python version\n\nBy default, reticulate uses an isolated python virtual environment named \"r-reticulate\".\n\nThe `use_python()` function enables you to specify an alternate python,\nfor example:\n\n``` r\nlibrary(reticulate)\nuse_python(\"/usr/local/bin/python\")\n```\n\nThe `use_virtualenv()` and `use_condaenv()` functions enable you to\nspecify versions of Python in virtual or Conda environments, for\nexample:\n\n``` r\nlibrary(reticulate)\nuse_virtualenv(\"myenv\")\n```\n\nSee the article on [Python Version\nConfiguration](https://rstudio.github.io/reticulate/articles/versions.html)\nfor additional details.\n\n#### Python packages\n\nYou can install any required Python packages using standard shell tools\nlike `pip` and `conda`. Alternately, reticulate includes a set of\nfunctions for managing and installing packages within virtualenvs and\nConda environments. See the article on [Installing Python\nPackages](https://rstudio.github.io/reticulate/articles/python_packages.html)\nfor additional details.\n\n#### Calling Python\n\nThere are a variety of ways to integrate Python code into your R\nprojects:\n\n1.  [Python in R Markdown](#python-in-r-markdown) — A new Python\n    language engine for R Markdown that supports bi-directional\n    communication between R and Python (R chunks can access Python\n    objects and vice-versa).\n\n2.  [Importing Python modules](#importing-python-modules) — The\n    `import()` function enables you to import any Python module and call\n    it’s functions directly from R.\n\n3.  [Sourcing Python scripts](#sourcing-python-scripts) — The\n    `source_python()` function enables you to source a Python script the\n    same way you would `source()` an R script (Python functions and\n    objects defined within the script become directly available to the R\n    session).\n\n4.  [Python REPL](#python-repl) — The `repl_python()` function creates\n    an interactive Python console within R. Objects you create within\n    Python are available to your R session (and vice-versa).\n\nEach of these techniques is explained in more detail below.\n\n## Python in R Markdown\n\nThe **reticulate** package includes a Python engine for [R\nMarkdown](https://rmarkdown.rstudio.com/) with the following features:\n\n1.  Run Python chunks in a single Python session embedded within your R\n    session (shared variables/state between Python chunks)\n\n2.  Printing of Python output, including graphical output from\n    [matplotlib](https://matplotlib.org/).\n\n3.  Access to objects created within Python chunks from R using the `py`\n    object (e.g. `py$x` would access an `x` variable created within\n    Python from R).\n\n4.  Access to objects created within R chunks from Python using the `r`\n    object (e.g. `r.x` would access to `x` variable created within R\n    from Python)\n\nBuilt in conversion for many Python object types is provided, including\n[NumPy](https://numpy.org/) arrays and\n[Pandas](https://pandas.pydata.org/) data frames. For example, you can\nuse Pandas to read and manipulate data then easily plot the Pandas data\nframe using [ggplot2](https://ggplot2.tidyverse.org/):\n\n![](man/figures/rmarkdown_engine_zoomed.png)\n\nNote that the reticulate Python engine is enabled by default within R\nMarkdown whenever reticulate is installed.\n\nSee the [R Markdown Python\nEngine](https://rstudio.github.io/reticulate/articles/r_markdown.html)\ndocumentation for additional details.\n\n## Importing Python modules\n\nYou can use the `import()` function to import any Python module and call\nit from R. For example, this code imports the Python `os` module and\ncalls the `listdir()` function:\n\n``` r\nlibrary(reticulate)\nos \u003c- import(\"os\")\nos$listdir(\".\")\n```\n\n``` text\n [1] \".git\"             \".gitignore\"       \".Rbuildignore\"    \".RData\"\n [5] \".Rhistory\"        \".Rproj.user\"      \".travis.yml\"      \"appveyor.yml\"\n [9] \"DESCRIPTION\"      \"docs\"             \"external\"         \"index.html\"\n[13] \"index.Rmd\"        \"inst\"             \"issues\"           \"LICENSE\"\n[17] \"man\"              \"NAMESPACE\"        \"NEWS.md\"          \"pkgdown\"\n[21] \"R\"                \"README.md\"        \"reticulate.Rproj\" \"src\"\n[25] \"tests\"            \"vignettes\"\n```\n\nFunctions and other data within Python modules and classes can be\naccessed via the `$` operator (analogous to the way you would interact\nwith an R list, environment, or reference class).\n\nImported Python modules support code completion and inline help:\n\n![](man/figures/reticulate_completion.png)\n\nSee [Calling Python from\nR](https://rstudio.github.io/reticulate/articles/calling_python.html)\nfor additional details on interacting with Python objects from within R.\n\n## Sourcing Python scripts\n\nYou can source any Python script just as you would source an R script\nusing the `source_python()` function. For example, if you had the\nfollowing Python script *flights.py*:\n\n``` python\nimport pandas\ndef read_flights(file):\n  flights = pandas.read_csv(file)\n  flights = flights[flights['dest'] == \"ORD\"]\n  flights = flights[['carrier', 'dep_delay', 'arr_delay']]\n  flights = flights.dropna()\n  return flights\n```\n\nThen you can source the script and call the `read_flights()` function as\nfollows:\n\n``` r\nsource_python(\"flights.py\")\nflights \u003c- read_flights(\"flights.csv\")\n\nlibrary(ggplot2)\nggplot(flights, aes(carrier, arr_delay)) + geom_point() + geom_jitter()\n```\n\nSee the `source_python()` documentation for additional details on\nsourcing Python code.\n\n## Python REPL\n\nIf you want to work with Python interactively you can call the\n`repl_python()` function, which provides a Python REPL embedded within\nyour R session. Objects created within the Python REPL can be accessed\nfrom R using the `py` object exported from reticulate. For example:\n\n![](man/figures/python_repl.png)\n\nEnter `exit` within the Python REPL to return to the R prompt.\n\nNote that Python code can also access objects from within the R session\nusing the `r` object (e.g. `r.flights`). See the `repl_python()`\ndocumentation for additional details on using the embedded Python REPL.\n\n## Type conversions\n\nWhen calling into Python, R data types are automatically converted to\ntheir equivalent Python types. When values are returned from Python to R\nthey are converted back to R types. Types are converted as follows:\n\n| R                                           | Python            | Examples                                         |\n|---------------------------------------------|-------------------|--------------------------------------------------|\n| Single-element atomic vector                | Scalar            | `1`, `1L`, `TRUE`, `\"foo\"`                       |\n| Unnamed list or multi-element atomic vector | List              | `c(1.0, 2.0, 3.0)`, `c(1L, 2L, 3L)`              |\n| Named list                                  | Dict              | `list(a = 1L, b = 2.0)`, `dict(x = x_data)`      |\n| Matrix/Array                                | NumPy ndarray     | `matrix(c(1,2,3,4), nrow = 2, ncol = 2)`         |\n| Data Frame                                  | Pandas DataFrame  | `data.frame(x = c(1,2,3), y = c(\"a\", \"b\", \"c\"))` |\n| Function                                    | Python function   | `function(x) x + 1`                              |\n| NULL, TRUE, FALSE                           | None, True, False | `NULL`, `TRUE`, `FALSE`                          |\n\nIf a Python object of a custom class is returned then an R reference to\nthat object is returned. You can call methods and access properties of\nthe object just as if it was an instance of an R reference class.\n\n## Learning more\n\nThe following articles cover the various aspects of using\n**reticulate**:\n\n-   [Calling Python from\n    R](https://rstudio.github.io/reticulate/articles/calling_python.html)\n    — Describes the various ways to access Python objects from R as well\n    as functions available for more advanced interactions and conversion\n    behavior.\n\n-   [R Markdown Python\n    Engine](https://rstudio.github.io/reticulate/articles/r_markdown.html)\n    — Provides details on using Python chunks within R Markdown\n    documents, including how call Python code from R chunks and\n    vice-versa.\n\n-   [Python Version\n    Configuration](https://rstudio.github.io/reticulate/articles/versions.html)\n    — Describes facilities for determining which version of Python is\n    used by reticulate within an R session.\n\n-   [Installing Python\n    Packages](https://rstudio.github.io/reticulate/articles/python_packages.html)\n    — Documentation on installing Python packages from PyPI or Conda,\n    and managing package installations using virtualenvs and Conda\n    environments.\n\n-   [Using reticulate in an R\n    Package](https://rstudio.github.io/reticulate/articles/package.html)\n    — Guidelines and best practices for using reticulate in an R\n    package.\n\n-   [Arrays in R and\n    Python](https://rstudio.github.io/reticulate/articles/arrays.html) —\n    Advanced discussion of the differences between arrays in R and\n    Python and the implications for conversion and interoperability.\n\n-   [Python\n    Primer](https://rstudio.github.io/reticulate/articles/python_primer.html)\n    — Introduction to Python for R users.\n\n## Why reticulate?\n\nFrom the [Wikipedia](https://en.wikipedia.org/wiki/Reticulated_python)\narticle on the reticulated python:\n\n\u003e The reticulated python is a species of python found in Southeast Asia.\n\u003e They are the world’s longest snakes and longest reptiles…The specific\n\u003e name, reticulatus, is Latin meaning “net-like”, or reticulated, and is\n\u003e a reference to the complex colour pattern.\n\nFrom the\n[Merriam-Webster](https://www.merriam-webster.com/dictionary/reticulate)\ndefinition of reticulate:\n\n\u003e 1: resembling a net or network; especially : having veins, fibers, or\n\u003e lines crossing a reticulate leaf. 2: being or involving evolutionary\n\u003e change dependent on genetic recombination involving diverse\n\u003e interbreeding populations.\n\nThe package enables you to *reticulate* Python code into R, creating a\nnew breed of project that weaves together the two languages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstudio%2Freticulate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frstudio%2Freticulate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstudio%2Freticulate/lists"}